FixMotor es una plataforma web autoalojada (self-hosted), rápida y transaccional diseñada para la administración integral de puntos de venta (POS), emisión de facturas y cotizaciones en PDF/HTML y WhatsApp, control de inventario valorizado (Costo vs. Venta) con lector de código de barras (SKU), directorio de proveedores, tablero Kanban de órdenes de taller en vivo, alertas preventivas de vehículos (SOAT, Tecnomecánica y Cambio de Aceite), arqueo de caja con control de cartera (créditos/abonos) y liquidación auditable de comisiones de mecánicos.
Construido bajo una arquitectura Monorepo Multicontenedor (Backend API REST Laravel 11 + Frontend React 19 + Base de Datos MariaDB 11.4), está optimizado para desplegarse tanto en servidores Linux VPS administrados con ALpanel como en entornos locales mediante un único archivo .env y docker compose.
A diferencia de sistemas POS genéricos que solo facturan productos sueltos de mostrador o agendas aisladas que no cruzan información con caja ni bodega:
-
🛒 Motor POS Híbrido (Repuestos + Mano de Obra + Cotizaciones sin Descuento de Stock):
- Permite facturar en una sola transacción repuestos físicos del inventario y servicios de mano de obra asignados a un técnico específico.
- Incluye modo Generar Cotización / Presupuesto Imprimible: calcula el total y genera el documento PDF/HTML o el mensaje de WhatsApp en 1 clic sin descontar unidades de la bodega ni afectar el cierre de caja hasta que el cliente apruebe el trabajo.
- Soporte nativo para Lector de Código de Barras / SKU: al escanear un código en el buscador del POS y presionar
Enter, el repuesto se agrega instantáneamente al carrito.
-
💳 Pagos Mixtos, Cartera de Clientes (Créditos / Abonos) y Arqueo de Caja Real:
- Soporta ventas en
Efectivo,Transferencia / Nequi,Tarjeta,Pago Mixto(combinando efectivo y transferencia con nota de desglose) yCrédito / Pendiente. -
Gestión de Cuentas por Cobrar: registra el monto pagado (
paid_amount) y el saldo pendiente (pending_balance), permitiendo realizar abonos parciales o saldar la deuda total posteriormente desde el módulo de Consultas (/look). - Módulo de Gastos Menores / Salidas de Caja: registra pagos operativos diarios (insumos, transporte, servicios) y los descuenta automáticamente en el Arqueo de Caja y Utilidad Neta Real.
- Soporta ventas en
-
📦 Inventario Valorizado (Costo vs. Venta), Margen Comercial y Proveedores:
- Cada producto controla su Código SKU, Costo de Compra Unitario (
cost_price), Precio de Venta (price), Stock Mínimo de Alerta (min_stock) y Proveedor asociado. - Calcula en tiempo real la Utilidad Unitaria ($), el Margen de Ganancia (%), el Capital Invertido en Bodega al Costo y el Valor Potencial de Venta.
- Al registrar una entrada de mercancía, permite actualizar el costo de compra unitario y documentar la factura o referencia del proveedor en el Kardex.
- Cada producto controla su Código SKU, Costo de Compra Unitario (
-
🛠️ Tablero Kanban de Taller en Vivo + Recepción Técnica con Kilometraje:
- Las órdenes de trabajo evolucionan visualmente a través de 5 etapas operativas:
Recibido$\rightarrow$ En Diagnóstico$\rightarrow$ Esperando Repuesto$\rightarrow$ En Reparación$\rightarrow$ Listo para Entrega. - Registra el kilometraje de ingreso (actualizando automáticamente el odómetro del vehículo) y las observaciones de recepción (estado físico, nivel de combustible, accesorios dejados).
- Cuando el cliente pasa a caja en
/sales, el POS detecta sus órdenes pendientes y precarga automáticamente los servicios realizados para facturarlos sin doble digitación.
- Las órdenes de trabajo evolucionan visualmente a través de 5 etapas operativas:
-
🔔 Alertas Preventivas (SOAT, Tecnomecánica y Aceite) + Notificaciones WhatsApp en 1 Clic:
- Semáforo automático en
/sales,/looky por consola (fixmotor:check-alerts) cuando un vehículo supera el kilometraje de su próximo cambio de aceite o tiene el SOAT / Tecnomecánica vencidos o próximos a vencer. - Integración directa con
wa.mesin costo de API externa para enviar: comprobantes de factura, cotizaciones detalladas, avisos de "Vehículo Listo para Entrega" y recordatorios preventivos al propietario.
- Semáforo automático en
-
👨🔧 Comisiones Configurables por Mecánico, Liquidación Auditable y Exportación Excel (CSV):
- Cada técnico posee su propio
% de Comisiónconfigurable (ej.60% Técnico / 40% Tallero50% / 50%). - Al cerrar el turno y pulsar Liquidar, el sistema ejecuta una transacción atómica que guarda el pago en el Historial Auditable de Liquidaciones (
WorkerSettlements) y reiniciatotalDia = 0. - Exportación contable inmediata a Excel (CSV con BOM UTF-8) desde
/reports,/looky por CLI Artisan.
- Cada técnico posee su propio
El sistema está dividido en tres capas desacopladas y orquestadas con Docker:
- Laravel 11 (
^11.9) sobre PHP 8.2 — Arquitectura por capas con Controladores REST, 7 Servicios de Dominio (app/Services/), 14FormRequests(app/Http/Requests/), 9JsonResources(app/Http/Resources/), 5 Comandos Artisan CLI (app/Console/Commands/) y transacciones ACID (DB::transaction). - Laravel Sanctum (
^4.0) — Autenticación stateless basada en tokens Bearer (Authorization: Bearer <token>). - Laravel Snappy PDF (
barryvdh/laravel-snappy+wkhtmltopdf) — Motor de renderizado de facturas comerciales en PDF y plantillas Blade HTML listas para impresión térmica o carta. - PHPUnit 11 (
^11.0.1) — Suite de 14 clases de pruebas automatizadas (FeatureyUnit) y 8Model Factoriespara validación continua.
-
React 19 (
^19.1.0) — Interfaz reactiva modular basada en componentes funcionales y Hooks. -
Vite 6 (
^6.3.2) — Servidor de desarrollo y bundler con proxy interno dinámico (/api$\rightarrow$ backend) y soporte de dominios externos (allowedHosts: true). -
Tailwind CSS v4 (
^4.1.4+@tailwindcss/vite) — Motor de estilos utilitarios para diseño responsivo de alta densidad visual. -
React Router DOM v7 (
^7.5.0) — Enrutamiento SPA con protección de rutas privadas (PrivateRoute). -
React Icons (
^5.5.0) — Iconografía vectorial para tableros Kanban, POS y reportes.
- MariaDB 11.4 LTS — Motor relacional con volumen persistente (
mariadb_data),healthcheckde auto-sincronización de credenciales y compatibilidad nativa con el inspector Base de Datos y Usuarios App de ALpanel. - Docker & Docker Compose v2 — Orquestación de los 3 contenedores (
fixmotor-mariadb,fixmotor-backend,fixmotor-frontend) en red bridge aislada (fixmotor-network).
git clone https://github.com/alexmargomez/FixMotor.git
cd FixMotor
cp .env.example .envToda la configuración del stack (puertos, credenciales de MariaDB, URLs y proxy entre contenedores) se controla desde un único archivo .env en la raíz:
# ==========================================
# Variables de Entorno - Docker Compose (Raíz)
# ==========================================
# 1. Puertos (Sincronizados automáticamente por ALpanel)
BACKEND_PORT=7000
FRONTEND_PORT=5173
DB_EXTERNAL_PORT=3309
# 2. Base de Datos (MariaDB 11.4)
DB_CONNECTION=mariadb
DB_HOST=fixmotor-mariadb
DB_PORT=3306
DB_DATABASE=fixmotor
DB_USERNAME=fixmotor_user
DB_PASSWORD=fixmotor_pass
DB_ROOT_PASSWORD=fixmotor_pass
# 3. Backend (Laravel 11 API)
APP_NAME="FixMotor"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:${BACKEND_PORT}
PHP_CLI_SERVER_WORKERS=4
# 4. Frontend (React 19 + Vite 6)
VITE_API_URL=/apidocker compose up -d --buildAl iniciar el stack, Docker Compose ejecuta el aprovisionamiento completo sin intervención manual:
fixmotor-mariadb(3309:3306): Inicializa MariaDB 11.4 y sincroniza la base de datosfixmotory el usuariofixmotor_userdefinidos en.env.fixmotor-backend(7000:7000): Espera a que MariaDB esté saludable (service_healthy), generaAPP_KEY, ejecuta todas las migraciones (php artisan migrate --force) y los datos semilla (php artisan db:seed --force).fixmotor-frontend(5173:5173): Levanta la SPA React 19 + Vite y redirige internamente/api/*haciahttp://backend:7000.
(Opcional) Si deseas poblar la base de datos con un catálogo demostrativo completo de repuestos valorizados, proveedores y técnicos con porcentajes de comisión:
docker exec -it fixmotor-backend php artisan db:seed --class=WorkshopCatalogSeederFixMotor sigue el estándar de 3 Variables de Puerto de ALpanel, permitiendo desplegarlo y vincularle un dominio HTTPS en segundos:
Variable en .env |
Comportamiento en ALpanel |
|---|---|
FRONTEND_PORT (5173) |
Puerto del contenedor fixmotor-frontend expuesto hacia el proxy inverso SSL (Caddy). |
BACKEND_PORT (7000) |
Puerto del contenedor fixmotor-backend (API Laravel 11) y destino del proxy interno de Vite. |
DB_EXTERNAL_PORT (3309) |
Puerto externo de MariaDB auto-asignado para conexiones desde DBeaver/TablePlus y backups .sql en 1 clic. |
| Usuario | Contraseña | Rol |
|---|---|---|
admin |
admin123 |
Admin |
Admin |
123456 |
Admin |
También puedes crear usuarios adicionales o actualizar contraseñas en caliente desde el botón
Usuarios Appde ALpanel.
El backend en API_REST/ implementa una arquitectura limpia desacoplada en Controladores, Servicios de Dominio (app/Services/), Validadores (app/Http/Requests/), Transformadores (app/Http/Resources/), Comandos CLI (app/Console/Commands/) y Pruebas Automatizadas (tests/):
FixMotor/
├── API_REST/ # ⚙️ BACKEND LARAVEL 11 (PHP 8.2 + Sanctum + SnappyPDF + PHPUnit)
│ ├── app/
│ │ ├── Console/Commands/ # 🖥️ Comandos Artisan CLI de Diagnóstico, Auditoría y Exportación
│ │ │ ├── AuditInventoryCommand.php # -> php artisan fixmotor:audit-inventory
│ │ │ ├── CheckVehicleAlertsCommand.php # -> php artisan fixmotor:check-alerts
│ │ │ ├── CashboxCloseSummaryCommand.php # -> php artisan fixmotor:cashbox-summary
│ │ │ ├── MechanicsSettlementReportCommand.php # -> php artisan fixmotor:mechanics-report
│ │ │ └── ExportAccountingCsvCommand.php # -> php artisan fixmotor:export-csv
│ │ ├── Http/
│ │ │ ├── Controllers/ # 🌐 Controladores RESTful de los 14 módulos de la API
│ │ │ │ ├── AnalyticsController.php # Consolidado ejecutivo financiero, bodega, Kanban y alertas
│ │ │ │ ├── SaleController.php # Ventas POS, pagos mixtos, créditos y abonos de cartera
│ │ │ │ ├── SaleDetailController.php # Descuento transaccional de stock y reversión
│ │ │ │ ├── ProductController.php # Catálogo SKU, costo vs venta y compras a proveedores
│ │ │ │ ├── SupplierController.php # Directorio de proveedores mayoristas
│ │ │ │ ├── ScheduleController.php # Órdenes de taller, kilometraje y flujo Kanban
│ │ │ │ ├── WorkerController.php # Técnicos, % de comisión y liquidación auditable
│ │ │ │ ├── ExpenseController.php # Gastos menores y salidas de caja para arqueo
│ │ │ │ ├── VehicleController.php # Vehículos, odómetro, próximo aceite, SOAT y Tecno
│ │ │ │ ├── CustomerController.php # Clientes y propietarios
│ │ │ │ ├── InvoiceController.php # Numeración FACT-XXXXXX y renderizado PDF/HTML
│ │ │ │ ├── InventoryController.php # Existencias en bodega
│ │ │ │ ├── InventoryMovementController.php # Kardex de entradas y salidas con costo unitario
│ │ │ │ └── ServiceController.php # Servicios de mano de obra e historial técnico
│ │ │ ├── Requests/ # 🛡️ 14 Clases FormRequest con reglas tipadas y mensajes en español
│ │ │ │ ├── StoreProductRequest.php / UpdateProductRequest.php
│ │ │ │ ├── StoreSaleRequest.php / UpdateSalePaymentRequest.php
│ │ │ │ ├── StoreScheduleRequest.php / UpdateScheduleRequest.php
│ │ │ │ ├── StoreVehicleRequest.php / UpdateVehicleRequest.php
│ │ │ │ ├── StoreSupplierRequest.php / UpdateSupplierRequest.php
│ │ │ │ ├── StoreCustomerRequest.php / UpdateCustomerRequest.php
│ │ │ │ ├── StoreWorkerRequest.php / SettleWorkerRequest.php
│ │ │ │ ├── StoreExpenseRequest.php
│ │ │ │ └── StoreInventoryMovementRequest.php
│ │ │ └── Resources/ # 📦 9 Clases Eloquent JsonResource con cálculos derivados
│ │ │ ├── ProductResource.php # Incluye unit_profit, margin_percentage y valorización
│ │ │ ├── SaleResource.php # Incluye estado de cartera y saldo pendiente
│ │ │ ├── VehicleResource.php # Incluye flags de alertas de aceite, SOAT y Tecno
│ │ │ ├── ScheduleResource.php
│ │ │ ├── WorkerResource.php # Incluye desglose pago técnico vs utilidad taller
│ │ │ ├── WorkerSettlementResource.php
│ │ │ ├── SupplierResource.php
│ │ │ ├── ExpenseResource.php
│ │ │ ├── CustomerResource.php
│ │ │ └── InventoryMovementResource.php
│ │ ├── Models/ # 🗄️ Modelos Eloquent Relacionales
│ │ │ ├── User.php, Customer.php, Vehicle.php, Category.php
│ │ │ ├── Product.php, Supplier.php, Inventory.php, InventoryMovement.php
│ │ │ ├── Sale.php, SaleDetail.php, Service.php, Invoice.php
│ │ │ └── Schedule.php, Worker.php, WorkerSettlement.php, Expense.php
│ │ └── Services/ # 🧠 Servicios de Dominio y Analítica Financiera
│ │ ├── FinancialReportService.php # Arqueo de caja, utilidad neta real y cartera por edades
│ │ ├── InventoryValuationService.php # Valorización de bodega al costo/venta y punto de reorden
│ │ ├── WorkshopKanbanService.php # Tablero Kanban y detector de alertas SOAT/Tecno/Aceite
│ │ ├── WorkerCommissionService.php # Liquidaciones atómicas y nómina técnica por porcentaje
│ │ ├── PosBillingService.php # Desglose de pagos mixtos/créditos y generador WhatsApp
│ │ ├── CsvAccountingExportService.php # Exportador contable CSV con BOM UTF-8 para Excel
│ │ └── CustomerLoyaltyAndHistoryService.php # Expediente técnico de clientes y ranking de productos
│ ├── database/
│ │ ├── factories/ # 🏭 9 Model Factories para pruebas automatizadas
│ │ ├── migrations/ # 📐 Migraciones relacionales (incluyendo Fases 1 a 4)
│ │ └── seeders/ # 🌱 DatabaseSeeder y WorkshopCatalogSeeder
│ ├── resources/views/ # 🧾 Plantillas Blade para facturas PDF y vista de impresión
│ ├── routes/api.php # 🔌 Definición de todos los endpoints RESTful bajo /api
│ └── tests/ # 🧪 Suite de 14 Clases de Pruebas Automatizadas (PHPUnit 11)
│ ├── Feature/ # 11 Suites de integración HTTP, BD, Comandos y Recursos
│ └── Unit/ # 3 Suites unitarias de matemáticas financieras y comisiones
│
├── Frontend/ # 🎨 FRONTEND SPA (React 19 + Vite 6 + Tailwind CSS v4)
│ ├── src/
│ │ ├── screens/
│ │ │ ├── dashboard.jsx # Panel principal de accesos rápidos
│ │ │ ├── sale.jsx # POS: Carrito, Lector SKU, Cotización, Pago Mixto y Crédito
│ │ │ ├── schedule.jsx # Recepción de vehículos y Tablero Kanban de Taller en vivo
│ │ │ ├── inventory.jsx # Inventario valorizado (Costo/Margen %), Compras y Proveedores
│ │ │ ├── look.jsx # Explorador unificado de 6 módulos con buscador instantáneo
│ │ │ └── report.jsx # KPIs, Utilidad Neta, Arqueo, Gastos, Comisiones y Exportación CSV
│ │ └── components/
│ │ ├── DatesRegister.jsx # Selector/alta de clientes y vehículos con alertas SOAT/Aceite
│ │ ├── LookProduct.jsx # Buscador de catálogo con lector de código de barras (Enter)
│ │ ├── LookDetail.jsx # Tablas interactivas, modal de Abonos de Cartera y Exportación CSV
│ │ ├── FactuView.jsx # Visor de facturas y envío de comprobantes por WhatsApp
│ │ ├── ReportCustomer.jsx # Expediente histórico de compras y servicios por cliente
│ │ └── ReportVehicle.jsx # Hoja de vida técnica por placa de vehículo
│ └── vite.config.js # Proxy dinámico /api -> backend y soporte multi-dominio
│
├── docker-compose.yml # 🐳 Orquestador de MariaDB 11.4 + Backend + Frontend
├── .env.example # 📋 Plantilla maestra de variables de entorno
└── README.md # 📖 Documentación integral del sistema
Puedes ejecutar cualquiera de los 5 comandos Artisan especializados directamente dentro del contenedor backend (docker exec -it fixmotor-backend php artisan <comando>):
| Comando Artisan | Opciones Disponibles | Descripción |
|---|---|---|
fixmotor:audit-inventory |
--only-alerts, --json |
Audita el inventario valorizado (capital al costo, venta potencial, utilidad proyectada, margen ponderado) y lista los SKUs bajo el stock mínimo. |
fixmotor:check-alerts |
--days=15, --km=500, --json |
Inspecciona el estado del tablero Kanban y detecta vehículos con cambio de aceite vencido/próximo, SOAT vencido o Tecnomecánica por vencer. |
fixmotor:cashbox-summary |
--from=YYYY-MM-DD, --to=YYYY-MM-DD, --json |
Genera el arqueo de caja completo: total facturado, recaudado, cartera por cobrar, utilidad en repuestos, mano de obra, gastos y utilidad neta real. |
fixmotor:mechanics-report |
--from=YYYY-MM-DD, --to=YYYY-MM-DD, --json |
Muestra el acumulado pendiente de liquidar por mecánico y el consolidado histórico de comisiones pagadas vs. utilidad retenida por el taller. |
fixmotor:export-csv |
--type=all|sales|inventory|settlements, --stdout |
Exporta los reportes contables en formato CSV (con BOM UTF-8 listo para Excel) en storage/app/exports/ o por salida estándar. |
El backend cuenta con 14 suites de pruebas automatizadas divididas entre pruebas de integración (tests/Feature/) y pruebas unitarias (tests/Unit/):
# Ejecutar toda la suite de pruebas dentro del contenedor Backend
docker exec -it fixmotor-backend php artisan test
# Ejecutar una suite específica (ej. Ventas POS, Créditos y Abonos)
docker exec -it fixmotor-backend php artisan test --filter=PosSalesAndReceivablesTestPosSalesAndReceivablesTest: Registro de ventas de contado, ventas a crédito con saldo pendiente, múltiples abonos parciales hasta saldar cartera y descuento automático de inventario en Kardex.InventoryValuationAndSuppliersTest: Creación de proveedores, alta de productos con SKU/costo/precio/stock mínimo, entradas de mercancía con actualización de costo unitario y endpoint de valorización de bodega.WorkshopKanbanAndVehicleAlertsTest: Creación de órdenes de trabajo con actualización automática del kilometraje del vehículo, transiciones por las 5 columnas del tablero Kanban y detección de alertas de aceite, SOAT y Tecnomecánica.WorkerCommissionsAndSettlementsTest: Configuración de porcentaje de comisión por técnico (%), acumulación de mano de obra diaria y liquidación transaccional auditable enWorkerSettlements.CashboxExpensesAndReportsTest: Registro de gastos menores de caja y verificación matemática de utilidad bruta de repuestos, mano de obra, flujo operativo de caja y utilidad neta real.AnalyticsEndpointsAndExportTest: Validación del endpoint ejecutivo/api/analytics/summary, exportación contable CSV y construcción de mensajes y enlaces profundos de WhatsApp (wa.me).SanctumAuthenticationAndSecurityTest: Emisión de tokens Bearer en/api/login, rechazo de credenciales inválidas, bloqueoHTTP 401en endpoints protegidos y revocación de tokens en/api/logout.CustomerAndVehicleHistoryReportTest: Trazabilidad histórica de repuestos y mantenimientos por cliente y por placa de vehículo, y generación de facturasFACT-XXXXXX.CustomerLoyaltyAndTopProductsTest: Consolidación del expediente financiero/técnico del cliente (CustomerLoyaltyAndHistoryService), ranking de productos más vendidos y ejecución idempotente deWorkshopCatalogSeeder.ArtisanDiagnosticCommandsTest: Ejecución automatizada de los comandos CLIfixmotor:audit-inventory,fixmotor:check-alerts,fixmotor:cashbox-summaryyfixmotor:mechanics-report.FormRequestValidationRulesTest: Validación exhaustiva de reglas y mensajes personalizados en español de las 14 clasesFormRequest.EloquentApiResourcesSerializationTest: Verificación de contratos JSON y campos calculados en las 9 clasesJsonResource.WorkerCommissionCalculationsUnitTest&InventoryValuationCalculationsUnitTest&FinancialAndMarginCalculationsTest: Pruebas unitarias puras en memoria de partición exacta de comisiones (0%a100%), márgenes comerciales, normalización de pagos mixtos/créditos y codificación CSV UTF-8 BOM.
Todas las rutas bajo /api (excepto POST /api/login) están protegidas mediante auth:sanctum (Authorization: Bearer <token>):
| Recurso | Endpoint Base | Operaciones | Descripción |
|---|---|---|---|
| Autenticación | /api/login, /api/logout |
POST |
Emisión y revocación de tokens Bearer Sanctum |
| Analítica Ejecutiva | /api/analytics/summary, /financial, /inventory-valuation, /vehicle-alerts |
GET |
Consolidado financiero, valorización de bodega, Kanban y alertas |
| Clientes | /api/customers |
GET, POST, PUT, DELETE |
CRUD de clientes y propietarios |
| Vehículos | /api/vehicles |
GET, POST, PUT, DELETE |
CRUD de vehículos, kilometraje, aceite, SOAT y Tecnomecánica |
| Proveedores | /api/suppliers |
GET, POST, PUT, DELETE |
Directorio de proveedores de repuestos e insumos |
| Productos | /api/products, /api/products/{id}/purchase |
GET, POST, PUT, DELETE |
Catálogo con SKU, costo de compra, precio de venta y stock |
| Inventario | /api/inventory |
GET, POST, PUT |
Consulta y ajuste de existencias en bodega |
| Movimientos Kardex | /api/inventory-movements |
GET, POST, PUT, DELETE |
Entradas y salidas con actualización de costo y reversión |
| Ventas y Cartera | /api/sales |
GET, POST, PUT, DELETE |
Ventas POS, pagos mixtos, créditos y registro de abonos |
| Detalles Venta | /api/sale-details, /api/sale-details/customer/{id} |
GET, POST, PUT, DELETE |
Ítems vendidos y descuento transaccional de stock |
| Mano de Obra | /api/services, /api/services/customer/{id}, /vehicle/{id} |
GET, POST |
Servicios por venta, cliente o placa de vehículo |
| Facturas PDF | /api/invoices, /api/invoices/pdf/{id} |
GET, POST, PUT, DELETE |
Numeración FACT-XXXXXX y visor PDF/HTML imprimible |
| Taller / Kanban | /api/schedules |
GET, POST, PUT, DELETE |
Órdenes de taller, kilometraje, notas y estados Kanban |
| Gastos de Caja | /api/expenses |
GET, POST, DELETE |
Salidas de caja menor y gastos operativos para arqueo |
| Mecánicos y Pagos | /api/workers, /api/workers/{id}/settle, /api/workers/settlements |
GET, POST, PUT, DELETE |
Técnicos, % de comisión y liquidaciones auditables |