# 🚴 Sistema de Gestión Lauck **Sistema web integral para gestión de bicicletería** - Inventario, ventas, taller, clientes y catálogo público. [![Laravel](https://img.shields.io/badge/Laravel-12-red.svg)](https://laravel.com) [![PHP](https://img.shields.io/badge/PHP-8.2+-blue.svg)](https://php.net) [![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4.0-38bdf8.svg)](https://tailwindcss.com) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) ## 📋 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 ### 🌐 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) ```php 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 (implementación futura) ``` #### 🎮 Controladores (app/Http/Controllers) ```php 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 ``` #### 👁️ 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 ```json { "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` ```sql 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` ```sql 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` ```sql 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` ```sql 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` ```sql 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) ```sql 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` ```sql 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 ```bash PHP >= 8.2 Composer >= 2.x Node.js >= 18.x NPM >= 9.x SQLite (o MySQL/PostgreSQL) ``` ### Instalación Paso a Paso ```bash # 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: ```bash 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 ```bash # Limpiar y recargar todo php artisan migrate:fresh --seed ``` ## 🎯 Próximas Funcionalidades (Roadmap) ### Prioridad Alta 🔴 #### 1. Sistema de Compras a Proveedores ``` Features: - Registrar pedidos a proveedores - Control de órdenes de compra - Recepción de mercadería - Actualización automática de stock - Historial de compras por proveedor ``` #### 2. 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**: ```javascript $('.select2-product').select2('destroy'); // Destruir const newRow = firstRow.clone(); // Clonar initSelect2(); // Re-inicializar todos ``` **Mejora sugerida**: ```javascript 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**: ```bash 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 ```php // 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 ```php // 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](https://laravel.com) - El framework PHP para artesanos web - [Tailwind CSS](https://tailwindcss.com) - Framework CSS utility-first - [Select2](https://select2.org) - Selectores avanzados - [jQuery](https://jquery.com) - 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**