# 📋 FLUJO COMPLETO DE RESERVAS - ESTADO ACTUAL

## 🔄 FLUJO ACTUAL DEL PROCESO

### 1️⃣ **CLIENTE - VERIFICAR DISPONIBILIDAD**
**Ubicación:** `public/index.html` - Sección "Disponibilidad"
- ✅ Cliente ingresa fechas (Desde/Hasta)
- ✅ Click en "Ver disponibles"
- ✅ Sistema muestra cantidad de lugares disponibles
- ⚠️ **PROBLEMA:** Solo muestra cantidad, NO muestra lugares específicos disponibles

**Endpoint usado:** `/api/availability?from=X&to=Y`
- Retorna: `{ activeTotal, occupied, free }`
- Solo números, sin detalles de lugares

---

### 2️⃣ **CLIENTE - CREAR RESERVA**
**Ubicación:** `public/index.html` - Sección "Reservar"
- ✅ Cliente completa formulario:
  - Nombre, Email
  - Matrícula, Marca, Modelo, Color del vehículo
  - Fechas (Desde/Hasta)
  - Fotos del vehículo (opcional)
- ✅ Click en "Reservar"
- ✅ Sistema crea reserva

**Endpoint usado:** `/api/reservations/capacity` (POST)
- ✅ Si hay capacidad: Crea reserva con `spotId: null` (sin asignar)
- ✅ Si NO hay capacidad: Agrega a lista de espera (`waitlist`)
- ✅ Crea factura automáticamente
- ⚠️ **PROBLEMA:** Cliente NO puede elegir lugar específico
- ⚠️ **PROBLEMA:** Cliente NO ve lugares disponibles antes de reservar

**Estados de reserva creada:**
- `status: 'confirmed'` (confirmada pero sin lugar asignado)
- `spotId: null` (esperando asignación por admin)

---

### 3️⃣ **ADMIN - VER RESERVAS SIN ASIGNAR**
**Ubicación:** `public/admin.html` - Sección "Asignación"
- ✅ Admin puede:
  - Buscar por email del cliente
  - Ver lista de reservas sin asignar
  - Seleccionar reserva de dropdown
- ✅ Muestra: Nombre cliente, fechas

**Endpoint usado:** `/api/reservations/unassigned`
- Retorna lista de reservas con `spotId: null`

---

### 4️⃣ **ADMIN - ASIGNAR LUGAR A RESERVA**
**Ubicación:** `public/admin.html` - Sección "Asignación" + "Mapa"
- ✅ Admin ingresa ID de reserva
- ✅ Admin hace click en lugar libre del mapa
- ✅ Sistema asigna lugar a la reserva

**Endpoint usado:** `/api/reservations/:id/assign` (POST)
- ✅ Valida que el lugar esté libre en el rango de fechas
- ✅ Asigna `spotId` a la reserva
- ✅ Soporta asignación por segmentos (si se especifican fechas diferentes)
- ⚠️ **PROBLEMA:** No hay confirmación visual clara de asignación exitosa
- ⚠️ **PROBLEMA:** No se notifica al cliente que su lugar fue asignado

**Flujo actual:**
1. Admin carga reservas sin asignar
2. Selecciona reserva del dropdown
3. Click en lugar libre del mapa
4. Sistema asigna automáticamente

---

### 5️⃣ **ADMIN - CHECK-IN**
**Ubicación:** `public/admin.html` - Sección "Check-in"
- ✅ Admin ingresa ID de reserva
- ✅ Sube fotos del vehículo
- ✅ Reconoce matrícula (opcional)
- ✅ Guarda placa en reserva
- ✅ Realiza check-in

**Endpoint usado:** `/api/ops/reservations/:id/checkin` (POST)
- ✅ Guarda `checkInAt` (timestamp)
- ✅ Guarda fotos en `photosCheckIn`
- ✅ Actualiza estado visual en mapa (ocupado)

---

### 6️⃣ **ADMIN - CHECK-OUT**
**Ubicación:** `public/admin.html` - Sección "Check-out"
- ✅ Admin ingresa ID de reserva
- ✅ Sube fotos del vehículo
- ✅ Reconoce matrícula
- ✅ Realiza check-out

**Endpoint usado:** `/api/ops/reservations/:id/checkout` (POST)
- ✅ Guarda `checkOutAt` (timestamp)
- ✅ Guarda fotos en `photosCheckOut`
- ✅ Libera el lugar en el mapa

---

### 7️⃣ **CLIENTE - VER SUS RESERVAS**
**Ubicación:** `public/index.html` - Sección "Mis reservas"
- ✅ Cliente ingresa su email
- ✅ Click en "Cargar"
- ✅ Ve lista de sus reservas
- ✅ Puede pagar o cancelar
- ⚠️ **PROBLEMA:** Cliente NO ve qué lugar le fue asignado
- ⚠️ **PROBLEMA:** Cliente NO sabe si su reserva fue confirmada con lugar

**Endpoint usado:** `/api/reservations?userEmail=X`
- Retorna todas las reservas del cliente

---

## ⚠️ PROBLEMAS IDENTIFICADOS

### 🔴 CRÍTICOS

1. **Cliente NO puede ver lugares disponibles antes de reservar**
   - Solo ve cantidad, no lugares específicos
   - No puede elegir lugar preferido

2. **Cliente NO sabe qué lugar le fue asignado**
   - En "Mis reservas" no se muestra el `spotId` asignado
   - No hay notificación cuando admin asigna lugar

3. **Falta flujo de confirmación/notificación**
   - Cliente no sabe cuándo su reserva tiene lugar asignado
   - No hay email o notificación automática

4. **Falta mostrar disponibilidad real en tiempo real**
   - El mapa del admin muestra disponibilidad según fechas
   - Pero el cliente no tiene acceso a esta información

### 🟡 MEJORAS NECESARIAS

1. **Sistema de estados más claro**
   - `pending` - Esperando asignación
   - `confirmed` - Con lugar asignado
   - `checked_in` - Cliente presente
   - `checked_out` - Cliente salió
   - `cancelled` - Cancelada

2. **Mejor visualización para cliente**
   - Mostrar lugares disponibles con colores
   - Permitir selección de lugar preferido
   - Mostrar lugar asignado en "Mis reservas"

3. **Notificaciones**
   - Email cuando se asigna lugar
   - Email recordatorio antes del check-in
   - SMS opcional

4. **Mejora en asignación admin**
   - Ver todas las reservas pendientes en un listado
   - Asignar múltiples reservas rápidamente
   - Ver conflictos antes de asignar

---

## 📊 ESTADOS ACTUALES DE RESERVA

```javascript
// Estados posibles:
'confirmed'  // Reserva creada (con o sin lugar asignado)
'paid'       // Reserva pagada
'cancelled'  // Cancelada

// Campos importantes:
spotId: null | "S-A1"  // null = sin asignar, string = lugar asignado
checkInAt: null | ISO  // null = no ha hecho check-in
checkOutAt: null | ISO  // null = no ha hecho check-out
```

---

## 🔧 ENDPOINTS DISPONIBLES

### Cliente
- `GET /api/availability?from=X&to=Y` - Ver disponibilidad (solo números)
- `POST /api/reservations/capacity` - Crear reserva sin lugar específico
- `GET /api/reservations?userEmail=X` - Ver mis reservas
- `DELETE /api/reservations/:id` - Cancelar reserva

### Admin
- `GET /api/reservations/unassigned` - Ver reservas sin asignar
- `POST /api/reservations/:id/assign` - Asignar lugar a reserva
- `GET /api/map?from=X&to=Y` - Ver mapa con disponibilidad
- `POST /api/ops/reservations/:id/checkin` - Check-in
- `POST /api/ops/reservations/:id/checkout` - Check-out
- `GET /api/reservations/waitlist` - Ver lista de espera
- `POST /api/reservations/waitlist/:id/promote` - Promover de waitlist

---

## 💡 RECOMENDACIONES DE IMPLEMENTACIÓN

### Prioridad ALTA
1. ✅ Mostrar lugares disponibles al cliente antes de reservar
2. ✅ Permitir al cliente elegir lugar preferido (opcional)
3. ✅ Mostrar lugar asignado en "Mis reservas"
4. ✅ Mejorar estados de reserva para mayor claridad

### Prioridad MEDIA
5. ⚠️ Sistema de notificaciones (email/SMS)
6. ⚠️ Mejorar UI de asignación para admin
7. ⚠️ Dashboard de reservas pendientes

### Prioridad BAJA
8. ⚠️ Sistema de recordatorios automáticos
9. ⚠️ Reportes de ocupación
10. ⚠️ Integración con sistemas de pago

---

## 📝 NOTAS ADICIONALES

- El sistema soporta **segmentos** (múltiples lugares para una reserva)
- El sistema tiene **lista de espera** automática cuando no hay capacidad
- El sistema calcula precios automáticamente según configuración
- El sistema valida conflictos antes de asignar lugares