FleetHub Documentación

Descripción general

FleetHub es un sistema de gestión de activos de flota empresarial para vehículos internos de la empresa (50–200 vehículos). Construido con Laravel 11, Vue 3 y Tailwind CSS — cubre vehículos, conductores, requisiciones, entregas con mapa de daños, registros de combustible, gastos, análisis TCO, seguimiento de cumplimiento y puntuación de salud de flota. No está diseñado para taxi ni alquiler de coches.

Requisitos del servidor

• PHP 8.2 o superior (se recomienda 8.3)
• MySQL 5.7+ o MariaDB 10.3+
• Composer 2.x (solo para desarrollo local; no es necesario en alojamiento compartido)
• Node.js 18+ y npm 9+ (solo para compilaciones de interfaz local)
• Servidor web: Apache o Nginx

Extensiones PHP requeridas

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

Espacio en disco

~ 200 MB mínimo. Deje espacio adicional para fotografías de vehículos, recibos de combustible, imágenes de entrega y documentos de cumplimiento.

Instalación

Opción A: instalador web (recomendado)

1. Cargue los archivos del proyecto a su servidor web.
2. Apunte la raíz del documento de su dominio a public/.
3. Establezca permisos: storage/ y bootstrap/cache/ deben poder escribirse (chmod 775).
4. Copie .env.example a .env y configure APP_KEY (ejecute php artisan key:generate si tiene SSH/Terminal, o consulte Configuración de cPanel → Paso 5).
5. Visita https://yourdomain.com/install en tu navegador.
6. Siga el asistente: Requisitos → Base de datos → Migrar → Cuenta de administrador → Listo. Marque Incluir datos de demostración para cargar una flota de muestra con cuentas de demostración (consulte Usuarios y roles).

Opción B: Instalación CLI

# 1. Instalar dependencias
composer install --no-dev --optimize-autoloader
npm install
npm run build

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

# 3. Edite .env para configurar las credenciales de base de datos
# DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 4. Cree tablas de bases de datos y genere datos iniciales.
php artisan migrate --seed

# 5. Cree un enlace simbólico de almacenamiento para las cargas.
php artisan storage:link

# 6. Configuración de caché para producción
php artisan config:cache
php artisan route:cache
php artisan view:cache

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

Paso 2 del asistente: Configuración de la base de datos

Cuando el asistente llegue al Paso 2, ingrese los detalles de la conexión MySQL para la base de datos que creó en su panel de alojamiento.

Dónde encontrar estas credenciales por panel de alojamiento

• Hostinger: hPanel → Bases de datos → Administración → haga clic en su base de datos.
• cPanel: cPanel → Bases de datos MySQL. La lista de bases de datos muestra nombres; Los usuarios se enumeran a continuación.
• Plesk: Plesk → Bases de datos → haga clic en el nombre de la base de datos.
• DirectAdmin: DirectAdmin → Administración de MySQL → haga clic en la base de datos.
• Base de datos externa/administrada: AWS RDS, base de datos administrada por DigitalOcean, etc. Utilice las credenciales de su consola en la nube.

Errores comunes y cómo solucionarlos

Localhost (Desarrollo Local)

Guía rápida para ejecutar FleetHub en su computadora para realizar pruebas o desarrollo antes de implementarlo en producción. Elija el entorno que coincida con su sistema operativo.

Opción 1: Laravel Herd (recomendado, macOS y Windows)

Laravel Herd es el entorno local oficial del equipo de Laravel: gratuito, nativo, sin Docker. Incluye PHP 8.2/8.3/8.4, Nginx y (en Herd Pro) MySQL/Redis.

1. Descargue e instale Laravel Herd desde herd.laravel.com.
2. Coloque la carpeta del proyecto FleetHub dentro de ~/Herd/ (macOS) o %USERPROFILE%\Herd\ (Windows). Herd crea automáticamente un dominio .test, p. http://fleethub.test.
3. Abra Herd → Sites y confirme que la versión de PHP es 8.2 o 8.3. Haga clic derecho en el sitio → Secure para habilitar HTTPS (necesario para el escáner QR).
4. Crea una base de datos MySQL. Con Herd Pro, use Servicios → MySQL → Abrir en TablePlus. De lo contrario, instale MySQL Community o use SQLite (DB_CONNECTION=sqlite, touch database/database.sqlite).
5. Copie .env.example a .env, complete las credenciales de la base de datos y luego ejecute php artisan key:generate desde la raíz del proyecto.
6. Abra http://fleethub.test/install en su navegador y siga el asistente de instalación.

Opción 2: XAMPP (Windows, macOS, Linux)

XAMPP incluye Apache, MySQL/MariaDB y PHP. Gratis y multiplataforma. Asegúrate de elegir una versión con PHP 8.2 o más reciente.

1. Descargue XAMPP 8.2+ desde apachefriends.org e instálelo.
2. Copie el proyecto FleetHub en C:\xampp\htdocs\FleetHub\ (Windows) o /Applications/XAMPP/htdocs/FleetHub/ (macOS).
3. Abra Panel de control XAMPP e inicie Apache y MySQL. Si los puertos están ocupados, use Config → service.conf para cambiar Apache a 8080.
4. Vaya a http://localhost/phpmyadmin → Nuevo → cree una base de datos llamada fleethub con intercalación utf8mb4.
5. En la carpeta del proyecto: copie .env.example a .env, configure DB_DATABASE=fleethub, DB_USERNAME=root, deje DB_PASSWORD vacío (valor predeterminado de XAMPP). Ejecute php artisan key:generate.
6. Visite http://localhost/FleetHub/public/install para ejecutar el asistente de instalación.

Opción 3: Laragon (Windows)

Laragon es una pila portátil de Windows diseñada para Laravel: vhosts automáticos, URL bonitas, MySQL/MariaDB y HeidiSQL incluido.

1. Descargue Laragon Full desde laragon.org e instálelo.
2. En Laragon: Menú → PHP → Versión - cambie a PHP 8.2 o 8.3.
3. Copie el proyecto FleetHub en C:\laragon\www\FleetHub\.
4. Haga clic en Iniciar todo. Laragon crea automáticamente el vhost: http://fleethub.test (apuntando a la carpeta public/).
5. Abra HeidiSQL (incluido) → cree una base de datos fleethub. Credenciales predeterminadas: usuario root, contraseña vacía.
6. Edite .env con las credenciales de la base de datos, ejecute php artisan key:generate y luego visite http://fleethub.test/install.

Opción 4: servidor PHP integrado (no se necesita servidor web)

La opción más simple: Laravel viene con artisan serve, que inicia un servidor PHP de desarrollo. No se requiere Apache ni Nginx. Lo mejor para pruebas rápidas.

# Instalar dependencias y configurar
cd /path/to/FleetHub
composer install
cp .env.example .env
php artisan key:generate

# Ejecutar migraciones y generar datos iniciales
php artisan migrate --seed

# Iniciar el servidor de desarrollo
php artisan serve
# Entonces visita: http://127.0.0.1:8000/install

Errores comunes del host local

La cámara del escáner QR no se abre en http://

Las API de la cámara del navegador requieren HTTPS, con una excepción: http://localhost y http://127.0.0.1 se tratan como contextos seguros. Si accede a FleetHub a través de su IP LAN (por ejemplo, http://192.168.1.10), la cámara se negará. Utilice localhost para desarrollo o habilite HTTPS a través de Herd/mkcert.

Permiso denegado en almacenamiento (macOS/Linux)

Si ve errores de escritura cuando la aplicación intenta iniciar sesión o almacenar en caché, corrija los permisos: chmod -R 775 storage bootstrap/cache. En Windows esto no suele ser necesario.

Puerto ya en uso

Si otra aplicación toma el puerto 8000, utilice un puerto diferente:

php artisan serve --port=8001

Probar correos electrónicos localmente

Real SMTP no está disponible en la mayoría de las configuraciones de host local. Dos opciones seguras: (1) configurar MAIL_MAILER=log en .env: los correos electrónicos se descargan en storage/logs/laravel.log en lugar de enviarse; o (2) use Mailtrap / MailHog para capturar el correo saliente en una bandeja de entrada falsa.

MAIL_MAILER=log
# Todos los correos electrónicos se escriben en Storage/logs/laravel.log.

Activos frontend (Vite / Tailwind)

La interfaz Vue/Tailwind de FleetHub está preconstruida en el paquete. Si edita componentes de Vue o la configuración de Tailwind, necesitará Node.js 18+:

npm install
npm run dev    # Recarga en caliente durante el desarrollo
npm run build  # Compilación de producción (ejecutar antes de implementar)

Implementación en Hostinger Single (Hosting compartido)

Esta es la ruta recomendada para usuarios sin VPS ni experiencia técnica. FleetHub es totalmente compatible con el plan Hostinger Single Web Hosting más económico (~$2,99/mes). Sin SSH, sin Composer, no se necesita línea de comando: Single incluye trabajos cron nativos, PHP 8.3 y SSL gratuito listo para usar.

Paso 1: prepara tu hosting

1. Inicie sesión en Hostinger hPanel.
2. Vaya a Hosting → Administrar para su dominio.
3. Configure la versión de PHP en 8.2 o 8.3 mediante Avanzado → Configuración de PHP.
4. Asegúrese de que estas extensiones PHP estén habilitadas (generalmente predeterminadas):
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo

Paso 2: crear una base de datos MySQL

1. En hPanel, vaya a Bases de datos → Bases de datos MySQL.
2. Haga clic en Crear nueva base de datos.
3. Tenga en cuenta estos 3 valores:
   • Nombre de la base de datos — p.ej. u123_FleetHub
   • Nombre de usuario — p.ej. u123_admin
   • Contraseña — generado automáticamente, mantenlo seguro

Paso 3: cargar archivos

1. Vaya a Archivos → Administrador de archivos en hPanel.
2. Navega hasta public_html/ (esta es la raíz de tu dominio).
3. Elimine cualquier index.html o default.php predeterminado en esa carpeta.
4. Haga clic en Cargar archivos y cargue el source.zip completo del paquete.
   O cargue el contenido de la carpeta /source/ directamente a través de FTP si lo prefiere.
5. Si cargó un ZIP, haga clic derecho → Extraer. Después de la extracción, todos los archivos deben estar en la raíz de public_html/.
6. Verifique que public_html/ contenga: app/, public/, vendor/, .htaccess, index.php (en public/), .env, etc.

Paso 4: ejecuta el instalador

1. Abra su navegador y vaya a https://yourdomain.com/install.
2. Verá el instalador de FleetHub.
3. Paso 1: Requisitos: todas las comprobaciones deben pasar (verde). Si alguno falla, comuníquese con el soporte de Hostinger para habilitar la extensión PHP que falta.
4. Paso 2: Base de datos: ingrese las credenciales del paso 2 anterior:
   • Anfitrión: localhost
   • Puerto: 3306
   • Base de datos: u123_FleetHub
   • Nombre de usuario: u123_admin
   • Contraseña: (la que generó Hostinger)
5. Paso 3: Migrar: haga clic en "Ejecutar migraciones y semillas". Tarda ~10 segundos. No actualices.
6. Paso 4: Administrador: crea tu cuenta de administrador. Utilice una contraseña segura.
7. ¡Listo!: verás la URL de Cron (¡guarda esto!) y un botón para iniciar sesión.

Paso 5: Configura alertas automáticas por correo electrónico a través de Hostinger Cron

FleetHub utiliza el programador de Laravel para tareas en segundo plano: alertas de vencimiento de cumplimiento, recordatorios de mantenimiento, avisos de solicitudes vencidas, alertas de licencias de conducir, actualizaciones del valor de los vehículos y recálculo del puntaje del estado de la flota. Configure el trabajo cron one en hPanel y Laravel decide qué tarea ejecutar y cuándo.

1. En hPanel, vaya a Avanzado → Trabajos cron.
2. Haga clic en Crear trabajo cron.
3. Seleccione el tipo: Personalizado (no "PHP"; debemos pasar un argumento).
4. Para el comando, ingrese (reemplace uXXXXXX con el nombre de usuario de su cuenta de Hostinger):

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

   Consejo: abra el Administrador de archivos, ubique el archivo artisan (raíz de su proyecto), haga clic derecho → Propiedades para copiar la ruta completa.
5. Establezca el horario en Cada minuto: los cinco campos (Minuto, Hora, Día, Mes, Día de la semana) configurados en *.
6. Haga clic en Guardar.

Eso es todo: FleetHub ahora envía recordatorios de solicitudes vencidas, alertas de mantenimiento, alertas de cumplimiento y vencimiento de licencias, actualiza los valores de depreciación de los vehículos y recalcula automáticamente la puntuación del estado de la flota.

Paso 6: configurar el correo electrónico (SMTP)

Hostinger proporciona cuentas de correo electrónico con cada plan. Para usarlos para notificaciones de FleetHub:

1. En hPanel, vaya a Correos electrónicos → Cuentas de correo electrónico y cree una (por ejemplo, noreply@yourdomain.com).
2. Edite el archivo .env en public_html/ a través del Administrador de archivos:

   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. Guarde el archivo.
4. Inicie sesión en FleetHub → Configuración → pestaña Correo electrónico → Enviar correo electrónico de prueba. Si lo recibes, ya está.

Problemas comunes en Hostinger Single

"Error interno del servidor 500" después de la carga

• Verifique que .htaccess exista en la raíz public_html/ y contenga las reglas de reescritura.
• Verifique que la versión de PHP esté configurada en 8.2 u 8.3 en hPanel.
• Verifique storage/logs/laravel.log a través del Administrador de archivos para ver el error real.

"Permiso denegado" en las cargas

Hostinger normalmente establece los permisos correctos, pero si no:

• Haga clic derecho en storage/ en Administrador de archivos → Permisos → configúrelo en 755 de forma recursiva.
• Lo mismo para bootstrap/cache/.

La cámara del escáner de código QR no se abre

Las API de la cámara del navegador requieren HTTPS. Hostinger proporciona SSL gratuito a través de Let's Encrypt; habilítelo en hPanel en SSL → Administrar.

Los correos electrónicos programados no se envían

• En hPanel → Trabajos cron → marque la columna Última ejecución en su entrada cron. Si está vacío, el cron no se activa; verifique que la ruta artesanal sea correcta.
• Pruebe el comando manualmente: abra Terminal en hPanel (si está disponible) y ejecute el comando cron. Si falla, el mensaje de error señalará el problema (versión PHP incorrecta, ruta incorrecta, etc.).
• Verifique que SMTP esté configurado correctamente (Configuración → Correo electrónico → Enviar prueba).
• Marque storage/logs/laravel.log para ver si hay errores en el programador.

Rendimiento lento

Hostinger Single tiene CPU/RAM compartida. Si su equipo tiene más de 20 usuarios, considere:

• Actualización a Premium (~$3,99/mes): servidores más rápidos, más recursos, múltiples bases de datos.
• O Business (~$5,99/mes): recursos dedicados, copias de seguridad diarias, entorno de prueba.

Implementación en cPanel (alojamiento compartido)

Esta guía cubre el alojamiento compartido estándar cPanel (Namecheap, Bluehost, GoDaddy y la mayoría de los hosts económicos). FleetHub se envía con vendor/ y recursos de interfaz prediseñados: no se requiere Composer, npm ni terminal web. Si su cPanel carece de Terminal, use Acceso SSH o las soluciones alternativas del Administrador de archivos a continuación.

Paso 1: configurar la versión y las extensiones de PHP

1. Inicie sesión en cPanel.
2. Abra MultiPHP Manager (o Seleccione la versión de PHP) y configure su dominio en PHP 8.2 o 8.3.
3. Abra Editor INI MultiPHP o Extensiones PHP y confirme que estén habilitadas:
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo
4. Si falta una extensión, habilítela en la lista de extensiones o comuníquese con el soporte de su proveedor de alojamiento.

Paso 2: habilite SSL (HTTPS)

1. Vaya a Estado SSL/TLS (o Cifremos SSL / AutoSSL).
2. Ejecute AutoSSL o instale un certificado gratuito para su dominio.
3. HTTPS es requerido para que el escáner QR del navegador acceda a la cámara.

Paso 3: crear una base de datos MySQL y un usuario

1. Abra Administrar mis bases de datos (en Bases de datos).
2. En Crear nueva base de datos, ingrese un nombre (por ejemplo, fleethub) y haga clic en Crear. cPanel agrega el prefijo de su cuenta automáticamente; el nombre completo se verá así cpaneluser_fleethub.
3. En Usuarios de MySQL, cree un usuario con una contraseña segura. Copie el nombre de usuario completo con el prefijo.
4. En Agregar usuario a la base de datos, seleccione el usuario y la base de datos, haga clic en Agregar y luego otorgue TODOS LOS PRIVILEGIOS. Es fácil pasar por alto este paso; sin él, se obtienen errores Access denied (1045).
5. Tenga en cuenta estos tres valores exactamente como se muestran en cPanel:
   • Nombre de la base de datos — p.ej. u123_FleetHub
   • Nombre de usuario — p.ej. u123_admin
   • Contraseña — generado automáticamente, mantenlo seguro

Paso 4: cargar archivos

1. Abra Administrador de archivos y vaya a public_html/ (la raíz del documento de su dominio).
2. Habilite Configuración → Mostrar archivos ocultos para que pueda ver .htaccess y .env.
3. Elimine cualquier index.html predeterminado en public_html/ si está presente.
4. Cargue el paquete source.zip y Extráigalo, o cargue el contenido de la carpeta /source/ a través de FTP.
5. Después de la extracción, public_html/ debe contener app/, public/, vendor/, raíz .htaccess y artisan en el mismo nivel.

Paso 5: prepare .env antes de ejecutar el instalador

Complete este paso antes de visitar /install. Laravel requiere un APP_KEY válido y una configuración de base de datos correcta en .env.

1. En el Administrador de archivos, copie .env.example a .env (la misma carpeta que artisan).
2. Edite .env y configúrelo al 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. Establezca DB_CONNECTION=mysql: el valor predeterminado .env.example usa SQLite; El alojamiento compartido requiere MySQL.
4. Establezca SESSION_DRIVER=file y CACHE_STORE=file antes de la primera migración (evita errores de "tabla de sesiones no encontrada").
5. Escriba DB_PASSWORD entre comillas dobles si contiene caracteres especiales (#, $, !, etc.).

Generar APP_KEY (no se requiere terminal)

Muchos planes de cPanel no incluyen una terminal web. Utilice uno de estos métodos:

• Acceso SSH (cPanel → Seguridad → Acceso SSH): conéctese con PuTTY o PowerShell, luego ejecute cd ~/public_html && php artisan key:generate.
• Ayudante del Administrador de archivos: cree public/genkey.php temporalmente, visítelo en su navegador, copie el resultado en APP_KEY= y luego elimine el archivo inmediatamente.

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

• En tu PC: si PHP está instalado localmente, ejecuta php -r "echo 'base64:'.base64_encode(random_bytes(32));" y pega el resultado en .env.

• Establezca los permisos storage/ y bootstrap/cache/ en 755 (recursivo) si el instalador informa errores de escritura.

Paso 6: ejecuta el instalador web

1. Abra https://yourdomain.com/install en su navegador.
2. Paso 1: Requisitos: todas las comprobaciones deben aprobarse (verde). Corrija las extensiones PHP que falten en el Paso 1 anterior.
3. Paso 2: Base de datos: ingrese los nombres con prefijo exactos del Paso 3:
   • Anfitrión: 127.0.0.1 or localhost
   • Puerto: 3306
   • Base de datos: cpaneluser_fleethub
   • Nombre de usuario: cpaneluser_admin
   • Contraseña: (your MySQL password)
4. Paso 3: Migrar: haga clic en "Ejecutar migraciones y semillas". Tarda ~10 segundos. No actualice la página.
5. Desmarque Incluir datos de demostración para una instalación de producción limpia.
6. Paso 4: Administrador: crea tu cuenta de administrador.
7. ¡Listo!: guarda la URL de Cron que se muestra en la pantalla final.

Paso 7: configurar trabajos cron para alertas por correo electrónico

FleetHub necesita un trabajo cron ejecutado cada minuto para que Laravel pueda enviar alertas de cumplimiento, recordatorios de mantenimiento, avisos de solicitudes vencidas y otros correos electrónicos programados.

1. En cPanel, vaya a Avanzado → Trabajos cron.
2. En Agregar nuevo trabajo cron, establezca la programación en Cada minuto (* * * * *).
3. Ingrese el comando (reemplace CPANELUSER con su nombre de usuario de cPanel en Información general):

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

   Consejo: la ruta PHP puede ser /usr/local/bin/php o /usr/bin/php; si no está seguro, pregúntele a su anfitrión. La ruta artesanal es donde subiste el proyecto (normalmente /home/CPANELUSER/public_html/artisan).
4. Haga clic en Agregar nuevo trabajo cron para guardar.

Paso 8: configurar el correo electrónico (SMTP)

Cree una cuenta de correo electrónico de cPanel para notificaciones salientes:

1. Vaya a Cuentas de correo electrónico → cree, por ejemplo. noreply@yourdomain.com.
2. Edite .env en el Administrador de archivos:

   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. Guarde y luego en FleetHub: Configuración → Correo electrónico → Enviar correo electrónico de prueba.

Problemas comunes en cPanel

"Acceso denegado al usuario" (SQLSTATE 1045)

• Copie el nombre de la base de datos y el nombre de usuario exactamente desde cPanel, incluido el prefijo de la cuenta.
• Confirme que completó Agregar usuario a la base de datos con TODOS LOS PRIVILEGIOS.
• Restablezca la contraseña de MySQL en cPanel y actualice .env; use comillas alrededor de DB_PASSWORD si contiene caracteres especiales.

La migración falla después de pasar el paso de la base de datos

• El asistente prueba las credenciales del formulario, pero Migrar dice .env. Asegúrate de que ambos coincidan.
• Elimine bootstrap/cache/config.php si existe y luego vuelva a intentarlo.
• Asegúrese de que DB_CONNECTION=mysql esté configurado en .env (no en sqlite).

"Valor predeterminado no válido" durante la migración (1067)

El modo estricto de MySQL en alojamiento compartido puede rechazar ciertos valores predeterminados de columnas. Marque storage/logs/laravel.log para ver el error de migración exacto y asegúrese de que PHP 8.2+ tenga todas las extensiones requeridas habilitadas.

"Error interno del servidor 500" después de la carga

• Verifique que exista la raíz .htaccess y que PHP sea 8.2+.
• Marque storage/logs/laravel.log para ver el error real.
• Confirme que APP_KEY está configurado en .env: la clave vacía provoca 500 errores.

Sin terminal en cPanel

Esto es normal en muchos planes compartidos. Utilice Acceso SSH (si está habilitado), el método temporal genkey.php en el Paso 5, o genere la clave en su PC local.

La cámara del escáner QR no se abre

Habilite SSL a través de SSL/TLS Status → AutoSSL y acceda al sitio a través de https://.

Configuración

Archivo .env

Configuración en la aplicación

La mayoría de las opciones no confidenciales se pueden configurar desde Admin → Configuración:

• General: nombre de la empresa/correo electrónico/teléfono, marca
• Flota: prefijo de código de vehículo, plantilla de lista de verificación de entrega, valores predeterminados de mantenimiento, modo de página de vehículo público
• Email: envía un correo electrónico de prueba para verificar SMTP
• Notificaciones: alternar alertas de cumplimiento, mantenimiento, solicitudes y licencias
• Localización: zona horaria, formato de fecha, moneda: se aplica en toda la aplicación
• Cumplimiento: gestiona los ajustes preestablecidos del tipo de cumplimiento (seguro, registro, impuesto de circulación, etc.)
• Branding: nombre y logotipo de la aplicación: actualiza el inicio de sesión, el pie de página y el título de la página del navegador
• Apariencia: personalice la marca, el estado y los colores del texto para el modo claro y oscuro; consulte la guía de cambio de marca en las preguntas frecuentes

Soporte multilingüe

FleetHub viene con 11 idiomas listos para usar, incluidos RTL árabe e hindi. Los usuarios cambian de idioma a través del menú desplegable de banderas en el encabezado superior derecho.

Idiomas enviados

Cómo cambiar de idioma

1. Haga clic en el icono de la bandera en el encabezado superior derecho para abrir el menú desplegable.
2. Elija su idioma de la lista.
3. La página se recarga; todas las etiquetas, fechas y formatos de moneda de la interfaz de usuario cambian.
4. Tu elección se guarda tanto en tu cuenta de usuario como en una cookie (1 año).

Agregar un idioma personalizado (admin)

Vaya a Administración → Traducciones (usuarios administradores con permiso administrar traducciones):

• Haga clic en "Agregar configuración regional": proporcione un código (por ejemplo, mk para macedonio), nombre para mostrar, nombre nativo, nombre de archivo SVG de la bandera, dirección (LTR/RTL) y una configuración regional base desde la cual copiar las traducciones.
• La nueva configuración regional aparece en el selector de idiomas y en Configuración → Lista de idiomas predeterminados de localización.
• Las traducciones almacenadas en la base de datos anulan automáticamente las traducciones de archivos en lang/{code}/.

Editor de traducción

El editor enumera todas las claves de traducción agrupadas por archivo (por ejemplo, recursos, navegación, configuración). Las claves muestran la línea base del archivo y cualquier anulación de la base de datos.

• Filtre por configuración regional, grupo de traducción o texto de búsqueda.
• Haga clic en un valor para editarlo en línea; Los cambios se guardan en la base de datos inmediatamente.
• Restablezca una clave para volver a la línea base del archivo.
• Las configuraciones regionales integradas (en, vi, es,…) se pueden editar; Las configuraciones regionales personalizadas están completamente basadas en DB.
• Solo los usuarios con el permiso administrar traducciones pueden acceder a esta página.

Importación/exportación CSV

• Exportar: descarga todas las claves de una configuración regional como CSV (group,key,value).
• Importar: sube un CSV con las mismas columnas; Las anulaciones de bases de datos existentes se actualizan y se insertan nuevas claves.

Configuración regional predeterminada por usuario

Cada usuario tiene una columna locale. Las notificaciones por correo electrónico se envían automáticamente en el idioma preferido del destinatario gracias al contrato HasLocalePreference de Laravel.

El idioma predeterminado del sitio se establece en Configuración → Localización → Idioma predeterminado. Los usuarios individuales anulan esto a través del selector de idioma del encabezado.

Lista de funciones (15 grupos de módulos)

Usuarios y roles

FleetHub se entrega con 5 roles preconfigurados para operaciones internas de la flota:

Cuentas demo (contraseña: password): admin@fleethub.test, manager@fleethub.test, dept@fleethub.test, accountant@fleethub.test, driver@fleethub.test. Habilite los datos de demostración durante la instalación o la inicialización. Los permisos son roles de Spatie: los administradores pueden ajustar cada permiso.

Gestión de vehículos

Creando vehículos

1. Navegue hasta Vehículos → Vehículo nuevo.
2. Complete la matrícula, marca, modelo, año, tipo de combustible, categoría y departamento.
3. Agregue la fecha de compra y el costo (obligatorio para la depreciación y el TCO).
4. Cargue imágenes (se admiten varios archivos, máximo 5 MB cada uno, comprimidos automáticamente en dispositivos móviles).
5. Guardar: el código del vehículo y el código QR se generan automáticamente.

Formato de código de vehículo

Predeterminado: {PREFIX}-{YEAR}-{NNNN}, p.e. VH-2026-0001. Configurable a través de Configuración → Flota → Prefijo de código de vehículo.

Importación masiva

1. Haga clic en Importar en la página Vehículos.
2. Descarga la plantilla de Excel.
3. Complete sus datos: columnas obligatorias: license_plate, make, model, category_name.
4. Sube el archivo.

Códigos QR y escaneo rápido

Cada vehículo recibe automáticamente un código QR al crearlo. El escaneo abre la página del vehículo público o acciones rápidas en la aplicación para conductores autenticados.

Impresión de etiquetas

• Etiqueta única: haga clic en el icono de la impresora en cualquier fila de vehículos.
• Impresión por lotes: seleccione varios vehículos → Imprimir etiquetas QR. Formato A4, 2 etiquetas por fila.

Escaneo en la aplicación

Haga clic en Escanear QR en la página Vehículos. Permitir permiso a la cámara. Funciona en cualquier navegador moderno con HTTPS o localhost.

Página de vehículos públicos

Cada vehículo tiene una URL pública en /v/{vehicle_code}, útil para una identificación rápida sin iniciar sesión.

• Configure en Configuración → Flota → Página de vehículos públicos: Público, Se requiere inicio de sesión o Deshabilitado.
• El modo invitado muestra información básica de solo lectura (placa, marca/modelo). Las acciones rápidas del conductor requieren iniciar sesión.
• Después de cambiar APP_URL, haga clic en Regenerar todos los códigos QR en Configuración.

Flujos de trabajo

Requisiciones de vehículos

Los empleados envían solicitudes de vehículos que necesitan. Flujo: requested → approved → returned (o rejected). El gerente de flota o el jefe de departamento lo aprueba. La vista de calendario muestra reservas para toda la flota. Las devoluciones vencidas activan alertas por correo electrónico.

Entrega de vehículos

1. Cuando se apruebe una solicitud, cree un entrega saliente antes de que el conductor tome el vehículo.
2. Registre el odómetro, complete la lista de verificación, marque daños en el mapeador 2D, adjunte fotografías y capture firma digital.
3. Guarde y descargue el informe de entrega en PDF para sus registros.
4. Cuando se devuelva el vehículo, cree una Entrega entrante: compare la condición, actualice el odómetro y borre la asignación del conductor.
5. Completar la entrega de entrada marca la requisición como devuelta y establece el vehículo como disponible.

Depreciación y coste total de propiedad

FleetHub calcula la depreciación del vehículo utilizando uno de tres métodos. La depreciación alimenta el panel de TCO junto con los registros y gastos de combustible.

Los valores predeterminados heredan de la categoría del vehículo. current_value se actualiza automáticamente mensualmente a través de fleethub:update-vehicle-values. TCO = costo de compra + suma de gastos del vehículo en el período seleccionado.

Campos personalizados

Administrador → Campos personalizados le permite agregar atributos personalizados ilimitados a los vehículos:

• Tipos: texto, número, fecha, selección (desplegable), área de texto, archivo, casilla de verificación
• Alcance: se aplica a todas las categorías o a una categoría de vehículo específica
• Reordenar: arrastra y suelta el controlador de agarre
• Los campos obligatorios se validan al guardar el vehículo.

Informes

Siete informes de flota integrados, accesibles desde el menú Informes:

1. Resumen de TCO: costo total de propiedad por vehículo y para toda la flota
2. Programa de depreciación — pérdida de valor por vehículo con exportación
3. Costo de mantenimiento: gasto por vehículo, tipo y mes
4. Consumo y costo de combustible — tendencias de km/l con anomalías destacadas
5. Uso de solicitud: porcentaje de reserva por vehículo a lo largo del tiempo
6. Caducidad del cumplimiento: los documentos del vehículo y las licencias de conducir vencerán pronto
7. Asignación de vehículos por departamento: vehículos y utilización por departamento

Todos los informes admiten la exportación Excel y PDF mediante botones en el encabezado de la página.

Ganchos web

FleetHub puede notificar a servicios externos sobre eventos clave de la flota.

Eventos disponibles

• 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
  }
}

Verificación de firma

Si se configura un secreto, las solicitudes incluyen el encabezado X-FleetHub-Signature que contiene HMAC-SHA256 del cuerpo de la carga útil. Verifique por su parte:

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

Política de reintento

Las entregas fallidas se reintentan 3 veces con un retraso de 200 ms. Después de 10 fallas consecutivas, el webhook se desactiva automáticamente.

Tareas programadas

FleetHub utiliza el programador de Laravel para trabajos en segundo plano. Solo necesita una entrada cron: Laravel envía cada comando fleethub: en el momento adecuado.

Alojamiento compartido (cPanel / Hostinger Cron Jobs UI)

Consulte Configuración de cPanel → Paso 7 o Configuración de Hostinger → Paso 5. En resumen: Avanzado → Trabajos cron, comando:

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

Horario: cada minuto (* en los cinco campos).

Comando cron de cPanel

Reemplace CPANELUSER con su nombre de usuario de cPanel:

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

VPS/servidor dedicado (crontab)

Ejecute crontab -e como su usuario web y agregue:

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

Alternativa: ping de URL externo

Si su host no tiene cron, use la URL de Cron en la aplicación (Configuración → pestaña Sistema) con cron-job.org (gratis, cada 15 minutos).

Trabajos que se ejecutan automáticamente

Guías de actualización

FleetHub v1.0.0 es el lanzamiento inicial en CodeCanyon.

Solución de problemas

"Permiso denegado" en el almacenamiento

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

El escáner de códigos QR no abre la cámara

Las API de la cámara del navegador requieren HTTPS. Instale SSL o use localhost para realizar pruebas.

Los correos electrónicos no llegan

Marque storage/logs/laravel.log. Utilice Configuración → Correo electrónico → Enviar correo electrónico de prueba para verificar SMTP.

Base de datos "Acceso denegado" (1045) en cPanel

Nombre de usuario/contraseña incorrectos o falta la asignación de usuario a base de datos. Consulte Configuración de cPanel → Problemas comunes.

Errores de migración en hosting compartido

Asegúrese de SESSION_DRIVER=file y CACHE_STORE=file en .env antes de la primera migración. Marque storage/logs/laravel.log para obtener más detalles.

Falta APP_KEY/error 500 antes de la instalación

Laravel requiere APP_KEY en .env. Consulte Configuración de cPanel → Paso 5 para conocer los métodos de generación sin Terminal.

Restablecer instalación

Elimina storage/installed.lock y visita /install nuevamente. Los datos existentes se borrarán si vuelve a ejecutar las migraciones.

Rendimiento: lista de vehículos lentos

Ejecute php artisan optimize. Asegúrese de que MySQL indexe en vehicles.vehicle_code, vehicles.license_plate, vehicles.status (creados por migraciones).

Registro de cambios

v1.0.0 — Lanzamiento inicial (2026-06)

• CRUD de vehículo con autogeneración de código QR y página pública en /v/{vehicle_code}
• 5 roles de usuario (administrador, administrador de flota, jefe de departamento, contable, conductor)
• Gestión de controladores con sincronización de vencimiento de licencia con elementos de cumplimiento
• Flujo de trabajo de solicitud de vehículos con calendario y alertas vencidas
• Entrega del vehículo con mapeador de daños 2D, lista de verificación, firma y PDF
• Gestión del registro de combustible con odómetro antifraude y sincronización de gastos automáticos
• Panel de gastos de vehículos y TCO con análisis de costo/km
• Motor de depreciación: línea recta, saldo decreciente, unidades de producción (km)
• Artículos de cumplimiento genéricos con alertas de vencimiento de 30/14/7/1 día
• Programación de mantenimiento con renovación automática preventiva y seguimiento de costos.
• Puntuación de salud de la flota con recálculo diario y modo de desglose
• 7 informes de flota con exportación a Excel y PDF
• Campos personalizados (7 tipos) enfocados a categorías de vehículos
• Webhooks con firma HMAC (X-FleetHub-Signature) y reintento automático
• Registro de auditoría a través de Spatie Activitylog con visor de diferencias
• Interfaz de usuario en varios idiomas: 11 idiomas, incluidos RTL árabe e hindi
• Configuración de interfaz de usuario para empresa, flota, correo electrónico, notificaciones y ajustes preestablecidos de cumplimiento
• Asistente de instalación basado en web con sembrador de datos de demostración
• Modo oscuro, interfaz de usuario móvil primero, compresión de imágenes para cargas

Créditos

Bibliotecas de código abierto utilizadas

• 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