🚴 Sistema de Gestión Lauck

Sistema web integral para gestión de bicicletería - Inventario, ventas, taller, clientes y catálogo público.

📋 Descripción

Lauck es un sistema de gestión completo diseñado específicamente para bicicleterías. Integra la gestión de inventario, ventas, taller mecánico, base de datos de clientes y un catálogo público para visitantes, todo en una única plataforma web moderna y responsiva.

✨ Características Principales

🔐 Sistema de Autenticación y Roles

• Registro de usuarios con validación completa
• Login seguro con rate limiting (5 intentos/minuto)
• Gestión de sesiones en base de datos
• Sistema de roles: Admin, Empleado, Invitado
• Protección de rutas con middleware
• Dashboard personalizado según permisos

📦 Gestión Avanzada de Productos

Atributos del Producto:

• Nombre, SKU (generación automática)
• Tipo: Bicicleta, Accesorio, Indumentaria, Repuesto
• Precio de venta y costo (solo admin)
• Stock actual y alerta de stock mínimo
• Descripción detallada
• Número de serie (para bicicletas)
• Imágenes con upload y visualización

Funcionalidades:

• ✅ CRUD completo (Crear, Leer, Actualizar, Eliminar)
• 🔍 Buscador avanzado (nombre, SKU)
• 🎨 Filtros dinámicos por estado de stock (Alerta, Bajo, Normal)
• 📊 Indicadores visuales de stock con colores (rojo/amarillo/verde)
• 🖼️ Gestión de imágenes con upload y storage
• 📄 Paginación optimizada (10 productos/página)
• 🏷️ Badges de tipo con diseño diferenciado

💰 Sistema de Ventas (POS)

Características del Punto de Venta:

• Interfaz intuitiva estilo POS moderno
• Selector de productos con Select2 y búsqueda en tiempo real
• Bloqueo de productos duplicados en el mismo ticket
• Cálculo automático de subtotales y total
• Gestión de clientes: Asociar venta a cliente o "Consumidor Final"
• Métodos de pago: Efectivo, Débito, Crédito, Transferencia
• Agregar/quitar productos dinámicamente
• Contador de items en tiempo real

Procesamiento de Ventas:

• ✅ Transacciones atómicas (rollback automático en caso de error)
• 📉 Descuento automático de stock al confirmar venta
• 💾 Registro de detalles (SaleDetails) por cada producto vendido
• 🧾 Comprobante imprimible en formato ticket profesional
• 📊 Historial de ventas con paginación

Comprobante de Venta:

• Diseño profesional tipo factura
• Header con logo y datos del negocio
• Información del cliente (o "Consumidor Final")
• Tabla detallada de productos
• Método de pago destacado
• Total en tamaño grande
• Botón de impresión/PDF optimizado
• Estilos específicos para impresión

👥 Gestión de Clientes

• Base de datos completa de clientes ciclistas
• Campos: Nombre, Teléfono/WhatsApp, Email, Dirección
• CRUD completo de clientes
• Búsqueda por nombre, teléfono o email
• Paginación de resultados
• Protección contra eliminación si tiene ventas registradas
• Integración con ventas: Seleccionar cliente en POS
• Creación rápida desde POS con redirección automática

🔧 Gestión de Taller (Mecánica)

Sistema Kanban de Órdenes de Reparación:

• Tablero visual estilo Trello con 3 columnas:
  • 🔴 Pendientes - Bicis recién ingresadas
  • 🟡 En Reparación - Trabajo en progreso
  • 🟢 Listas para Retirar - Trabajos finalizados

Información de Orden:

• Cliente asociado
• Modelo y color de bicicleta
• Descripción del problema
• Lista de repuestos necesarios con precios
• Presupuesto estimado (calculado automáticamente)
• Fecha/hora prometida de entrega
• Teléfono de contacto rápido
• Notas del mecánico

Funcionalidades Kanban:

• ✅ Mover cards entre estados (flechas)
• ↩️ Regresar al estado anterior si es necesario
• 💬 Botón de WhatsApp para avisar al cliente
• ✔️ Marcar como entregado (archiva la orden)
• 🎨 Bordes de color según estado
• 📱 Scroll independiente por columna
• 🔢 Contador de items por columna

Creación de Orden:

• Selector de cliente con búsqueda
• Auto-completar teléfono al seleccionar cliente
• Buscador de repuestos en tiempo real
• Lista visual de repuestos seleccionados
• Cálculo automático del presupuesto total
• Validación completa de datos
• Botón de crear cliente sin salir del formulario

🏭 Proveedores y Compras

• Base de datos de proveedores: Registro y gestión de datos de contacto
• Órdenes de compra: Generación de pedidos a proveedores para reabastecimiento
• Actualización de inventario: Vinculación con los productos para reponer stock

📅 Agenda de Turnos

• Calendario integrado: Visualización y gestión de citas del taller
• Detalle de turno: Información rápida de los turnos programados

💸 Control de Gastos

• Registro de egresos: Control de pagos de servicios, insumos y otros gastos del local
• Categorización: Descripción y fecha para tener seguimiento de los gastos

💾 Copias de Seguridad (Backups)

• Generación manual: Creación de respaldos completos de la base de datos (Solo Administradores)
• Gestión de archivos: Descarga, restauración y eliminación de copias de seguridad
• Interfaz dedicada: Panel de control específico para proteger la información

🌐 Catálogo Público

Vista para Visitantes (sin login):

• Listado público de productos en stock
• Cards atractivos con imagen, nombre, precio
• Búsqueda integrada en navbar
• Paginación automática (12 productos/página)
• Vista de detalle profesional con:
  • Imagen a tamaño completo
  • Información completa del producto
  • Indicador de stock en tiempo real
  • Precio destacado
  • Botones de contacto (teléfono, WhatsApp)
  • Diseño responsivo premium

Carrousel Destacados:

• Slider automático de productos destacados
• Controles manuales (flechas y puntos)
• Auto-play cada 5 segundos
• Diseño dual: Imagen + Info
• Precio flotante con efecto
• Navegación fluida con transiciones

🎨 Sistema de Diseño

Paleta de Colores Personalizada:

• Neon Lime (#ccff00): Color principal/acción
• Dark Background (#1a1a1a): Fondo principal
• Panel Background (#242424): Paneles/tarjetas
• Neutral 800/900: Componentes UI
• Gradientes: Efectos visuales modernos

Componentes Reutilizables:

components/
├── layout.blade.php          # Layout principal autenticado
├── appc.blade.php            # Layout público (visitantes)
├── navbar.blade.php          # Navegación contextual
├── footer.blade.php          # Pie de página
├── section-header.blade.php  # Encabezados de sección
├── taller-card.blade.php     # Card de orden de taller
├── ui/
│   ├── alert.blade.php       # Alertas de feedback
│   ├── badge.blade.php       # Etiquetas de estado
│   ├── card.blade.php        # Tarjetas de dashboard
│   ├── imgcard.blade.php     # Card de producto con imagen
│   └── carrousel.blade.php   # Carrousel de destacados
└── forms/
    ├── input.blade.php       # Input con validación
    ├── label.blade.php       # Label estandarizado
    └── select.blade.php      # Select estilizado

Efectos Visuales:

• 🌟 Patrón de grilla de fondo con efecto técnico
• 💫 Hover states en todos los elementos interactivos
• 🎭 Transiciones suaves en navegación
• 📱 Diseño responsivo 100% mobile-first
• 🎨 Scrollbar personalizado con colores del tema
• ⚡ Loading indicators donde corresponde

🏗️ Arquitectura del Sistema

Flujo de Navegación Completo

┌────────────────────────────────────────────────────┐
│                 Landing Page (/)                    │
│  - Carrousel de productos destacados                │
│  - Navbar con catálogo público                      │
│  - Botón "Ingresar" para staff                      │
└─────────────────┬──────────────────────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
    VISITANTE            STAFF
        │                   │
        ▼                   ▼
┌──────────────┐    ┌──────────────┐
│   Catálogo   │    │    Login     │
│   Público    │    │              │
│  /catalogo   │    │   /login     │
└──────────────┘    └──────┬───────┘
        │                   │
        │                   ▼
        │           ┌──────────────┐
        │           │  Dashboard   │
        │           │ (autenticado)│
        │           └──────┬───────┘
        │                  │
        │      ┌───────────┼───────────┬──────────┐
        │      │           │           │          │
        ▼      ▼           ▼           ▼          ▼
    ┌─────┐ ┌─────┐   ┌──────┐   ┌───────┐  ┌─────┐
    │ Ver │ │Stock│   │Ventas│   │Clientes│ │Taller│
    │Prod.│ │/prod│   │/sales│   │/clients│ │/taller│
    └─────┘ └─────┘   └──────┘   └────────┘ └─────┘

Estructura MVC Detallada

📁 Modelos (app/Models)

User.php          // Usuarios con roles (admin/employee/guest)
Product.php       // Productos con relaciones
Client.php        // Clientes con validaciones
Sale.php          // Ventas (cabecera)
SaleDetail.php    // Detalles de venta (renglones)
Appointment.php   // Órdenes de taller
Supplier.php      // Proveedores y pedidos
Expense.php       // Gastos del local

🎮 Controladores (app/Http/Controllers)

HomeController.php            // Landing page con destacados
LoginController.php           // Autenticación
RegisterController.php        // Registro de usuarios
ProductosController.php       // CRUD de productos
SaleController.php            // Sistema de ventas (POS)
ClientController.php          // Gestión de clientes
TallerController.php          // Gestión de taller (Kanban)
CatalogoController.php        // Catálogo público
ExpenseController.php         // Gestión de gastos
AgendaController.php          // Agenda de turnos
AppointmentController.php     // Detalle de turnos
SupplierController.php        // Proveedores y pedidos
Admin/BackupController.php    // Copias de seguridad (Admin)

👁️ Vistas (resources/views)

views/
├── welcome.blade.php              # Landing page
├── login.blade.php                # Inicio de sesión
├── register.blade.php             # Registro
├── dashboard.blade.php            # Panel principal
├── productos/
│   ├── index.blade.php            # Listado de productos
│   ├── create.blade.php           # Crear producto
│   ├── edit.blade.php             # Editar producto
│   └── show.blade.php             # Ver detalle
├── sales/
│   ├── index.blade.php            # Historial de ventas
│   ├── create.blade.php           # POS (punto de venta)
│   └── show.blade.php             # Comprobante de venta
├── clients/
│   ├── index.blade.php            # Listado de clientes
│   ├── create.blade.php           # Alta de cliente
│   └── edit.blade.php             # Modificar cliente
├── taller/
│   ├── index.blade.php            # Tablero Kanban
│   └── create.blade.php           # Nueva orden
└── catalogo/
    ├── index.blade.php            # Catálogo público
    └── show.blade.php             # Detalle producto público

🚀 Stack Tecnológico

Backend

• Laravel 12.x - Framework PHP moderno
• PHP 8.2+ - Lenguaje de programación
• SQLite - Base de datos (configurable a MySQL/PostgreSQL)
• Eloquent ORM - Gestión de base de datos
• Laravel Factories & Seeders - Datos de prueba

Frontend

• Tailwind CSS 4.0 - Framework CSS utility-first
• Blade Components - Sistema de componentes reutilizables
• jQuery 3.7.1 - Manipulación DOM
• Select2 4.1 - Selectores avanzados con búsqueda
• Vite 7.0 - Build tool y HMR
• Montserrat Font - Tipografía principal

JavaScript/Bibliotecas

{
  "jquery": "^3.7.1",
  "select2": "^4.1.0-rc.0",
  "axios": "^1.8.2"
}

Herramientas de Desarrollo

• Composer - Gestor de dependencias PHP
• NPM - Gestor de paquetes JavaScript
• Laravel Pint - Code styling
• Laravel Sail - Entorno Docker (opcional)
• Concurrently - Múltiples procesos en desarrollo

📊 Base de Datos

Esquema Completo

Tabla: users

id                  BIGINT PRIMARY KEY
name                VARCHAR(255)
email               VARCHAR(255) UNIQUE
role                ENUM('admin', 'employee', 'guest')
email_verified_at   TIMESTAMP NULLABLE
password            VARCHAR(255)
remember_token      VARCHAR(100) NULLABLE
created_at          TIMESTAMP
updated_at          TIMESTAMP

Tabla: products

id                  BIGINT PRIMARY KEY
name                VARCHAR(255)
sku                 VARCHAR(50) UNIQUE NULLABLE
description         TEXT NULLABLE
price               DECIMAL(10,2)
cost                DECIMAL(10,2) NULLABLE
stock_quantity      INTEGER DEFAULT 0
min_stock_alert     INTEGER
type                ENUM('bike','accessory','clothing','spare')
serial_number       VARCHAR(100) NULLABLE
image_path          VARCHAR(255) NULLABLE
suppliers_id        BIGINT FOREIGN KEY
created_at          TIMESTAMP
updated_at          TIMESTAMP

Tabla: clients

id                  BIGINT PRIMARY KEY
name                VARCHAR(255)
phone               VARCHAR(50) NULLABLE
email               VARCHAR(255) NULLABLE UNIQUE
address             TEXT NULLABLE
created_at          TIMESTAMP
updated_at          TIMESTAMP

Tabla: sales

id                  BIGINT PRIMARY KEY
client_id           BIGINT FOREIGN KEY NULLABLE
total               DECIMAL(10,2)
payment_method      VARCHAR(255)
created_at          TIMESTAMP
updated_at          TIMESTAMP

Tabla: sale_details

id                  BIGINT PRIMARY KEY
sale_id             BIGINT FOREIGN KEY ON DELETE CASCADE
product_id          BIGINT FOREIGN KEY
quantity            INTEGER
price               DECIMAL(10,2)
created_at          TIMESTAMP
updated_at          TIMESTAMP

Tabla: appointments (Taller)

id                  BIGINT PRIMARY KEY
client_id           BIGINT FOREIGN KEY ON DELETE CASCADE
contact_phone       VARCHAR(50) NULLABLE
scheduled_at        DATETIME
bike_model          VARCHAR(255)
problem_description TEXT
parts_needed        TEXT NULLABLE
estimated_cost      DECIMAL(10,2) NULLABLE
status              ENUM('pending','in_progress','ready','delivered')
notes               TEXT NULLABLE
created_at          TIMESTAMP
updated_at          TIMESTAMP

Tabla: suppliers

id                  BIGINT PRIMARY KEY
name                VARCHAR(255)
phone               VARCHAR(50)
email               VARCHAR(255)
created_at          TIMESTAMP
updated_at          TIMESTAMP

Relaciones del Modelo

User (1) ──────────── (N) Sale
Client (1) ────┬───── (N) Sale
               └───── (N) Appointment
Product (1) ──┬─────── (N) SaleDetail
              └─────── (1) Supplier
Sale (1) ────────────── (N) SaleDetail

🚀 Instalación

Requisitos Previos

PHP >= 8.2
Composer >= 2.x
Node.js >= 18.x
NPM >= 9.x
SQLite (o MySQL/PostgreSQL)

Instalación Paso a Paso

# 1. Clonar el repositorio
git clone https://github.com/tu-usuario/lauck.git
cd lauck

# 2. Instalar dependencias de PHP
composer install

# 3. Instalar dependencias de JavaScript
npm install

# 4. Configurar variables de entorno
cp .env.example .env

# 5. Generar clave de aplicación
php artisan key:generate

# 6. Crear base de datos SQLite
touch database/database.sqlite

# 7. Configurar .env (verificar estas líneas)
DB_CONNECTION=sqlite
DB_DATABASE=/ruta/absoluta/database/database.sqlite

# 8. Ejecutar migraciones
php artisan migrate

# 9. Poblar base de datos con datos de prueba
php artisan db:seed

# 10. Crear enlace simbólico para imágenes
php artisan storage:link

# 11. Compilar assets para desarrollo
npm run dev
# O para producción:
npm run build

# 12. Iniciar servidor de desarrollo
php artisan serve

Desarrollo Concurrente (Recomendado)

Laravel incluye un script dev en composer.json que ejecuta:

composer run dev

Esto inicia simultáneamente:

• 🌐 Servidor PHP (puerto 8000)
• 📦 Queue listener
• 📋 Pail (logs en tiempo real)
• ⚡ Vite (HMR)

Acceso a la Aplicación

URL Principal:  http://localhost:8000
Catálogo:       http://localhost:8000/catalogo
Admin:          http://localhost:8000/dashboard

Credenciales de Prueba (Seeder)

Administrador:

• Email: admin@lauck.com
• Password: password

Empleado:

• Email: taller@lauck.com
• Password: password

🧪 Datos de Prueba

El seeder carga automáticamente:

• ✅ 2 usuarios (1 admin, 1 empleado)
• ✅ 1 proveedor genérico
• ✅ 50+ productos variados (bicis, accesorios, repuestos)
• ✅ 1 cliente de ejemplo
• ✅ 1 orden de taller de ejemplo

# Limpiar y recargar todo
php artisan migrate:fresh --seed

🎯 Próximas Funcionalidades (Roadmap)

Prioridad Alta 🔴

1. Reportes y Estadísticas

Dashboard mejorado con:
- Ventas del día/mes/año (gráficos)
- Productos más vendidos
- Stock crítico (alertas)
- Rendimiento por categoría
- Clientes frecuentes
- Exportación a PDF/Excel

3. Sistema de Usuarios Completo

- Gestión de empleados
- Permisos granulares por módulo
- Registro de actividad (logs)
- Auditoría de cambios

4. Mejoras en el POS

- Descuentos por producto/venta
- Venta a crédito / financiación
- Múltiples formas de pago en una venta
- Impresión directa de tickets
- Devoluciones y notas de crédito

Prioridad Media 🟡

5. Notificaciones Automáticas

- Email de comprobante de venta
- WhatsApp API para avisos de taller
- Recordatorios de retiro
- Alertas de stock bajo

6. Historial de Taller Completo

- Archivo de trabajos entregados
- Búsqueda de histórico por cliente
- Estadísticas de reparaciones
- Reputación del mecánico

7. Catálogo Mejorado

- Sistema de categorías jerárquicas
- Comparador de productos
- Favoritos/Wishlist
- Reseñas de clientes
- Galería de múltiples imágenes

8. Integración con MercadoPago/Stripe

- Pagos online para catálogo
- Reservas con seña
- Panel de conciliación

Prioridad Baja 🟢

9. App Móvil (PWA)

- Instalable como app
- Notificaciones push
- Modo offline básico

10. Integraciones

- Sincronización con contabilidad
- API pública RESTful
- Webhooks para eventos
- Importación masiva (Excel/CSV)

11. Marketing

- Email marketing a clientes
- Campañas promocionales
- Cupones de descuento
- Programa de puntos/fidelidad

12. Multi-sucursal

- Gestión de múltiples locales
- Transferencias entre sucursales
- Stock por local
- Reportes consolidados

🐛 Issues Conocidos y Soluciones

1. Select2 no se inicializa en filas dinámicas

Problema: Al agregar nueva fila en POS, Select2 no funciona.

Solución actual:

$('.select2-product').select2('destroy'); // Destruir
const newRow = firstRow.clone(); // Clonar
initSelect2(); // Re-inicializar todos

Mejora sugerida:

function addRow() {
    const newRow = firstRow.clone();
    container.append(newRow);
    newRow.find('.select2-product').select2({ /* config */ });
}

2. Imágenes no se muestran después de upload

Problema: Falta ejecutar storage:link.

Solución:

php artisan storage:link

3. Error en eliminación de cliente con ventas

Problema: Violación de constraint de foreign key.

Solución implementada: Try-catch con mensaje amigable.

Mejora: Soft deletes

// En migración
$table->softDeletes();

// En modelo
use SoftDeletes;

4. Problema de concurrencia en stock

Escenario: Dos ventas simultáneas del mismo producto.

Solución recomendada: Optimistic locking

// En modelo Product
protected $casts = [
    'version' => 'integer'
];

// Al actualizar
Product::where('id', $id)
    ->where('version', $currentVersion)
    ->update([
        'stock_quantity' => $newStock,
        'version' => $currentVersion + 1
    ]);

📝 Convenciones y Estándares

Nombres

• Variables: camelCase ($productoActual)
• Funciones: camelCase (getUserData())
• Clases: PascalCase (ProductController)
• Tablas: snake_case plural (products, sale_details)
• Rutas: kebab-case (/productos/crear)

Commits

Add: Nueva funcionalidad
Fix: Corrección de bugs
Update: Actualización de código existente
Refactor: Refactorización sin cambios funcionales
Docs: Cambios en documentación
Style: Formato/estilo (sin cambios lógicos)
Test: Agregar/modificar tests
Chore: Tareas de mantenimiento

Branches

main/master     - Producción
Bryam           - Desarrollo particular de Bryam
Lucas           - Desarrollo particular de Lucas
Giane           - Desarrollo particular de Giane

🤝 Contribuir

Proceso

1. Fork del proyecto
2. Crear rama: git checkout -b (Tu Nombre)
3. Commit: git commit -m 'Add: nueva funcionalidad'
4. Push: git push origin (Tu Nombre)
5. Abrir Pull Request

Checklist antes del PR

• Código sigue las convenciones
• Tests pasan (php artisan test)
• No hay errores de linting (composer run lint)
• Documentación actualizada
• Migraciones incluidas si aplica
• Seeders actualizados si aplica

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver archivo LICENSE para detalles.

🙏 Agradecimientos

• Laravel - El framework PHP para artesanos web
• Tailwind CSS - Framework CSS utility-first
• Select2 - Selectores avanzados
• jQuery - Manipulación DOM simplificada
• Comunidad de Laravel por su excelente documentación

📞 Contacto

Bicicletería Lauck

• Dirección: Av. Francisco Ramírez 1389, Paraná, Entre Ríos
• Teléfono: 343 422-0103
• Web: En desarrollo

---

Versión: 0.2.0
Estado: En desarrollo activo 🚧
Última actualización: Enero 2026

Desarrollado con ❤️ para Bicicletería Lauck