# Módulo de Motocicletas — Cómo Funciona

Este documento explica exclusivamente el **módulo de Motocicletas** (inventario): cómo entra una moto al sistema, cómo se consulta, cómo se edita, cómo se le agregan costos y documentos, y cómo se elimina. No cubre ventas, contratos ni ningún otro módulo.

---

## 1. ¿Qué es este módulo?

Es el **inventario de motocicletas** del negocio. Cada motocicleta registrada representa un vehículo físico que la empresa tiene disponible para vender. El módulo controla:

- Los datos técnicos de cada moto (nombre, modelo, color, placa, matrícula, números de identificación).
- A qué empresa pertenece.
- Cuánto costó comprarla y a qué proveedor.
- Los costos adicionales que se le suman después de comprarla (lavada, papeleo, repuestos, etc.).
- Sus documentos legales (SOAT, revisión técnico-mecánica, tarjeta de propiedad).
- Si está disponible para la venta o no.

---

## 2. Cómo entra una moto al sistema (Registrar Compra)

No existe un botón de "Crear motocicleta" por separado — una moto **siempre nace de una compra**. El flujo es:

1. El usuario entra a **Inventario → Nueva Compra** (`compras/create`).
2. Elige la **Empresa** a la que pertenecerá la moto (campo obligatorio, select).
3. Llena los datos de la motocicleta:
   - Nombre (ej. "Yamaha FZ 2.0"), Modelo (ej. "2024"), Color — obligatorios.
   - Placa — obligatoria y **única en todo el sistema** (no puede repetirse entre motos, aunque sean de empresas distintas).
   - Matrícula — opcional, sin restricción de unicidad.
   - Stock — opcional, por defecto 1.
   - Números de identificación (motor, serie, chasis) — opcionales, se convierten a mayúsculas automáticamente en el formulario.
4. Llena los datos de la compra:
   - Proveedor (texto libre — si no existe, se crea automáticamente con ese nombre).
   - Fecha de compra (no puede ser futura).
   - Precio de compra.
   - Notas opcionales.
5. Opcionalmente sube los documentos vehiculares (SOAT, Revisión Técnica, Tarjeta de Propiedad) desde el mismo formulario, en pestañas.
6. Al guardar, el sistema crea en una sola operación: la **Motocicleta** (queda con estado `disponible` por defecto), el **Proveedor** (si no existía), el registro de **Compra**, y los **Documentos Vehiculares** que se hayan subido.

---

## 3. Inventario (listado)

Ruta: **Inventario** (`motocicletas.index`). Solo muestra motos con estado `disponible` (las vendidas no aparecen aquí).

**Filtros disponibles** (todos se aplican contra la base de datos, no solo en pantalla):
- Búsqueda por texto: nombre, placa, matrícula, modelo, color o nombre del proveedor.
- Empresa (select).
- Rango de fechas de compra (desde / hasta).

**Columnas mostradas:** Empresa, Nombre, Modelo, Color, Placa, Matrícula, Proveedor, Precio de Compra, Costos Adicionales, Costo Total (compra + costos), Fecha de Compra, Estado, y accesos directos a Costos y Acciones (Editar / Eliminar / Crear Contrato).

**Totales en la parte superior:** cantidad de motos, inversión total (suma de precios de compra), costos adicionales totales, y costo total combinado — todos recalculados según los filtros aplicados.

La paginación de esta tabla es distinta a la del resto del sistema: en vez de pedirle páginas al servidor, carga **todas** las motos que cumplen el filtro y las pagina con JavaScript en el navegador (50 por página).

---

## 4. Editar una motocicleta

Ruta: `motocicletas/{id}/edit`. Desde aquí se puede modificar:

- **Empresa** a la que pertenece (select editable — permite reasignarla a otra empresa si fue mal registrada).
- Todos los datos técnicos de la moto (nombre, modelo, color, placa, matrícula, números de identificación).
- Los datos de la compra vigente (proveedor, fecha, precio, notas) — actualiza el registro de compra más reciente asociado.
- Los documentos vehiculares (SOAT, Revisión Técnica, Tarjeta de Propiedad): se puede subir un archivo nuevo (reemplaza el anterior, borrando el archivo físico viejo) y/o actualizar la fecha de vencimiento, todo por pestañas.

**Nota:** no existe una pantalla de "Ver detalle" (`show`) funcional — la ruta existe registrada en el sistema, pero la vista no está creada, así que intentar abrirla generaría un error. En la práctica, todo el flujo de consulta pasa por el índice y por Editar.

---

## 5. Costos Adicionales

Ruta: `motocicletas/{id}/costos` (botón "Costos" en el inventario). Permite agregar una lista libre de conceptos de gasto (no una lista fija — cada fila tiene un "concepto" en texto libre y un "valor"), por ejemplo: lavada, calcomanías, impuestos, repuestos, etc.

- Al guardar, el sistema **borra todos los conceptos anteriores y los reemplaza** por los que se enviaron en el formulario (no los va acumulando).
- El **total** se recalcula automáticamente como la suma de todos los conceptos.
- Ese total es el que se usa en el inventario para mostrar "Costos Adicionales" y "Costo Total" de cada moto.
- El formulario guarda un borrador automático en el navegador (localStorage) mientras se escribe, para no perder el trabajo si se recarga la página por accidente.

---

## 6. Documentos Vehiculares

Cada moto puede tener hasta tres documentos asociados: **SOAT**, **Revisión Técnico-Mecánica** y **Tarjeta de Propiedad**. Cada uno guarda: número de documento, fecha de expedición, fecha de vencimiento, archivo (PDF, JPG o PNG, máximo 5MB) y observaciones.

Estos documentos se cargan o actualizan **desde el mismo formulario de Compra o de Edición de la moto** — no existe una pantalla independiente para gestionarlos en el sistema actualmente (existe un módulo separado construido para esto, pero no tiene ninguna ruta activa, así que no es accesible).

Los archivos se guardan físicamente en `public/documentos_vehiculares/{PLACA}/`, organizados por carpeta según la placa de la moto.

---

## 7. Eliminar una motocicleta

Desde el inventario, botón "Eliminar". Reglas:

- **No se puede eliminar una moto que ya fue vendida** (si tiene una venta asociada, el sistema bloquea la acción con un mensaje de error).
- Si se puede eliminar, el sistema borra en cascada: los archivos físicos de sus documentos y la carpeta de documentos, el registro de costos adicionales, y todo su historial de compras — y finalmente la moto. Es una **eliminación definitiva** (no queda en papelera / soft delete).

---

## 8. Estado de la moto

Cada moto tiene un campo `estado` con dos valores posibles: **disponible** o **vendida**. El inventario solo muestra las disponibles. Este módulo por sí solo nunca cambia una moto a "vendida" — eso ocurre en otro punto del sistema cuando se concreta una venta (fuera del alcance de este documento).

---

## 9. Relación con Empresas

Cada motocicleta pertenece a una única empresa (`empresa_id`, obligatorio). Esa empresa se elige al registrar la compra y se puede corregir después desde Editar. El proveedor asociado a la compra también queda ligado a esa misma empresa. Esto permite filtrar el inventario por empresa cuando el negocio maneja más de una.

---

## 10. Resumen del flujo completo

```
Nueva Compra (elige empresa, llena datos de moto + compra + documentos)
        ↓
Se crean: Motocicleta (disponible) + Proveedor (si no existía) + Compra + Documentos
        ↓
Aparece en el Inventario (filtrable por empresa, fecha, texto)
        ↓
Se le pueden agregar Costos Adicionales (recalculan el costo total)
        ↓
Se puede Editar en cualquier momento (datos, empresa, documentos)
        ↓
Se puede Eliminar (si no ha sido vendida) o queda disponible hasta que se venda
```