# 🚴 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

### 🏭 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)
```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 y pedidos
Expense.php       // Gastos del local
```

#### 🎮 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
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
```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. 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**