LauckCycles/resources/a.md

¡Perfecto\! Tus respuestas aclaran muchísimo el panorama. Al ser un sistema **Intranet (Local)** con un **Admin** y **Empleados** (visores/operadores), y con procesos manuales en el taller, podemos simplificar la arquitectura para lanzar un MVP (Producto Mínimo Viable) rápido y robusto, pero preparado para crecer.

Aquí tienes la **Guía Maestra de Desarrollo para Lauck Systems**.

-----

### 1\. Arquitectura de Base de Datos (El Cimiento)

Antes de escribir código, definamos las tablas. Laravel hace esto fácil con migraciones.

#### Tablas Principales:

1.  **`users`** (Ya viene en Laravel)

      * Agregamos campo: `role` (enum: 'admin', 'employee').
      * *Lógica:* El Admin crea, edita y borra. El Empleado solo ve y registra ventas/turnos (según definas).

2.  **`clients`** (Clientes)

      * `name`, `phone` (clave para WhatsApp), `email`, `address`.
      * *Nota:* Fundamental para agendar turnos y registrar garantías.

3.  **`products`** (Inventario Mixto)

      * `name`, `sku` (código único), `description`.
      * `price` (precio venta), `cost` (costo, solo visible para admin).
      * `stock_quantity` (entero).
      * `min_stock_alert` (entero, para la alerta que pediste).
      * `type` (enum: 'bike', 'accessory', 'service').
      * `serial_number` (nullable, solo para bicicletas).

4.  **`appointments`** (Turnos / Taller)

      * `client_id` (relación).
      * `scheduled_at` (datetime - fecha y hora del turno).
      * `bike_model` (texto libre, ej: "Venzo Loki 29").
      * `problem_description` (motivo de la consulta).
      * `status` (enum: 'pending', 'confirmed', 'in\_progress', 'ready', 'delivered').
      * `notes` (uso interno del mecánico).

5.  **`sales`** (Ventas Internas / Historial)

      * `user_id` (quién vendió).
      * `client_id` (opcional, si es consumidor final anónimo).
      * `total_amount`.
      * `payment_method` (efectivo, tarjeta, transferencia).
      * `created_at` (fecha de venta).

6.  **`sale_items`** (Detalle de venta)

      * `sale_id`, `product_id`, `quantity`, `unit_price`.

-----

### 2\. Estructura de Rutas y Controladores (Backend)

En Laravel, organizaremos esto por "Dominios".

  * **Autenticación:** (Ya lo tienes con Breeze/Jetstream).
  * **DashboardController:**
      * `index()`: Muestra las tarjetas, alertas de stock bajo (query simple `Product::whereColumn('stock', '<=', 'min_stock')->get()`) y turnos de hoy.
  * **ProductController:**
      * CRUD completo (Crear, Leer, Actualizar, Borrar).
      * Función extra `search()`: Para el buscador de precios de los empleados.
  * **ClientController:**
      * CRUD simple.
  * **AppointmentController (Gestión de Taller):**
      * `calendar()`: Vista de calendario o lista cronológica.
      * `statusUpdate()`: Para mover el turno de "Pendiente" a "Listo".
  * **SaleController:**
      * `create()`: Formulario para registrar una salida de mercadería.
      * `store()`: Resta el stock y guarda la venta.

-----

### 3\. Componentes de UI (Frontend - Blade + Tailwind)

Para mantener el estilo "Lauck" que ya definimos, necesitaremos crear estos componentes reutilizables (además de los que ya tienes):

1.  **`x-ui.status-badge`**:
      * Una etiqueta pequeña redondeada que cambia de color según el estado (Verde para 'Stock Alto', Rojo para 'Sin Stock' o 'Turno Atrasado', Amarillo para 'En Reparación').
2.  **`x-ui.table`**:
      * Una tabla estilizada con el modo oscuro, filas alternadas y cabeceras fijas. Vital para listas de precios y clientes.
3.  **`x-forms.input` / `x-forms.select`**:
      * Inputs con el estilo oscuro y borde neón al hacer foco, para no repetir las clases de Tailwind en cada formulario.
4.  **`x-ui.alert`**:
      * Para mostrar mensajes de éxito ("Producto guardado") o alertas ("¡Quedan solo 2 cámaras rodado 29\!").

-----

### 4\. Funcionalidades Específicas a Implementar

Aquí está la lógica para los requerimientos que mencionaste:

#### A. Alertas de Stock ⚠️

  * **Lógica:** No necesitas un sistema complejo de notificaciones en tiempo real todavía.
  * **Implementación:** En el `DashboardController`, pasas una variable `$lowStockProducts` a la vista.
  * **Vista:** En el Dashboard, si esa lista no está vacía, muestras una tarjeta roja o amarilla avisando "X productos con stock crítico".

#### B. Consulta de Precios (Modo Solo Lectura) 🔍

  * **Requerimiento:** Empleados consultan, no editan.
  * **Implementación:**
      * Crear una vista `products.checker`.
      * Un input de búsqueda grande en el centro.
      * Al escribir (AJAX o Livewire sería ideal aquí, pero un form simple con botón "Buscar" funciona), muestra una tarjeta gigante con el Nombre y el Precio.
      * *Seguridad:* Usar **Laravel Gates** o **Policies**.
        ```php
        // En AuthServiceProvider
        Gate::define('edit-products', function ($user) {
            return $user->role === 'admin';
        });
        ```
        En Blade: `@can('edit-products') <button>Editar</button> @endcan`. Así el empleado ve el producto pero no el botón de editar.

#### C. Agenda de Turnos 📅

  * **Lógica:** "Consulta -\> Cita".
  * **Implementación:**
      * No te compliques con un calendario visual complejo (tipo Google Calendar) al principio.
      * Usa una **Lista Agrupada por Días**.
      * *Ejemplo visual:*
          * **HOY:**
              * 09:00 - Jose (Pincharura) [Ver]
              * 10:30 - Maria (Service General) [Ver]
          * **MAÑANA:**
              * ...

-----

### 5\. Roadmap Sugerido (Paso a Paso)

Este es el orden lógico para programar sin perderse:

1.  **Semana 1: Cimientos y Stock (Lo más urgente)**

      * Configurar Migraciones (`products`, `clients`).
      * Crear Modelos y Seeders (datos falsos para probar).
      * Hacer el CRUD de Productos (Alta, Baja y Modificación).
      * *Hito:* Poder cargar una bicicleta y verla en la lista.

2.  **Semana 2: Seguridad y Consultas**

      * Agregar campo `role` a Users.
      * Crear la vista "Consulta de Precios" (solo lectura).
      * Proteger las rutas de edición para que solo el Admin entre.
      * *Hito:* El empleado puede loguearse y buscar un precio, pero no borrar nada.

3.  **Semana 3: El Taller (Turnos)**

      * Crear migración `appointments`.
      * Crear formulario para "Nuevo Turno" (Seleccionar Cliente + Fecha + Motivo).
      * Crear vista de "Lista de Turnos" en el Dashboard.
      * *Hito:* Dejar de usar el cuaderno de papel para los turnos.

4.  **Semana 4: Refinamiento**

      * Alertas de stock visuales.
      * Mejoras estéticas (Dark Mode en tablas).
      * Pruebas finales en el servidor local.

### ¿Cómo seguimos?

¿Te gustaría que generemos el código para la **Migración de Productos** y el **Modelo**, o prefieres que diseñemos primero el componente visual de la **Tabla de Stock**?