# Vehicle Mapper - Documentación

## Problema Resuelto

La API de Dominicana de Seguros requiere **marca, modelo y versión** por separado, mientras que MasterOne almacena **marca** y **modelo+versión combinados** en un solo campo.

### Ejemplo del problema:

**MasterOne:**
```
Marca: TOYOTA
Modelo: FJ CRUISER TRAIL TEAM
```

**Dominicana API requiere:**
```json
{
  "cdMarca": "229",
  "cdModelo": "11",
  "cdVersion": "2",
  "deIndiceDato": "229|11|2"
}
```

## Solución: VehicleMapper

La clase `VehicleMapper` realiza un mapeo inteligente entre los datos de MasterOne y la estructura requerida por Dominicana API.

### Características

✅ **Búsqueda Exacta**: Intenta encontrar coincidencias exactas primero
✅ **Búsqueda por Similitud**: Si no encuentra exacta, busca parciales y por similitud
✅ **Extracción Inteligente del Modelo Base**: Separa el modelo de su versión automáticamente
✅ **Cache**: Almacena en cache las llamadas a la API para mejor rendimiento
✅ **Fallback**: Si falla, usa el método legacy como respaldo
✅ **Logging**: Registra todo el proceso para debugging

### Algoritmo de Mapeo

1. **Mapear Marca**
   - Busca la marca en el catálogo de Dominicana API
   - Primero búsqueda exacta, luego por similitud
   - Retorna: `cdMarca` (ej: "229" para TOYOTA)

2. **Extraer Modelo Base**
   - De "FJ CRUISER TRAIL TEAM" extrae "FJ CRUISER"
   - Elimina patrones comunes de versión (TRD, LE, LIMITED, etc.)
   - Aplica reglas inteligentes para identificar el modelo base

3. **Mapear Modelo**
   - Busca el modelo base en los modelos de la marca
   - Retorna: `cdModelo` (ej: "11" para FJ CRUISER)

4. **Mapear Versión**
   - Busca la versión específica dentro del modelo
   - Compara "TRAIL TEAM" con las versiones disponibles
   - Si no encuentra exacta, usa la primera versión disponible
   - Retorna: `cdVersion` (ej: "2" para TRAIL TEAM)

### Patrones de Versión Reconocidos

El mapper reconoce y extrae automáticamente estos patrones:

- TRAIL TEAM
- TRD
- LE, SE, XLE
- LIMITED, SPORT, PREMIUM, DELUXE
- EXECUTIVE, PLATINUM
- TURBO, HYBRID
- GT, GTS, RS

## Integración

### En TransactionManager

El `VehicleMapper` se integra automáticamente en `TransactionManager`:

```php
private function prepararDatosVehiculo($transaccion) {
    $mapper = new VehicleMapper($this->dominicanaAPI, $this->logger);

    try {
        // Mapear el vehículo
        $vehicleMapped = $mapper->mapVehicle(
            $transaccion['marca'],
            $transaccion['modelo']
        );

        // Construir datos para Dominicana API
        $datosVehiculo = [
            ['cdTabla' => 600010, 'deIndiceDato' => $vehicleMapped['cdMarca']],
            ['cdTabla' => 600011, 'deIndiceDato' => $vehicleMapped['cdMarca'] . '|' . $vehicleMapped['cdModelo']],
            ['cdTabla' => 600013, 'deIndiceDato' => $vehicleMapped['deIndiceDato']],
            // ... más campos
        ];

        return $datosVehiculo;

    } catch (Exception $e) {
        // Fallback al método legacy si falla
        return $this->prepararDatosVehiculoLegacy($transaccion);
    }
}
```

### Respuesta del Mapper

```php
[
    'cdMarca' => '229',           // Código de marca
    'cdModelo' => '11',            // Código de modelo
    'cdVersion' => '2',            // Código de versión
    'deIndiceDato' => '229|11|2',  // Formato completo para API
    'nombreMarca' => 'TOYOTA',     // Nombre descriptivo
    'nombreModelo' => 'FJ CRUISER',
    'nombreVersion' => 'FJ CRUISER TRAIL TEAM'
]
```

## Testing

### Página de Pruebas

Accede a: `/admin/test_vehicle_mapper.php`

Características:
- 🧪 **Prueba Individual**: Prueba un vehículo específico
- 📋 **Casos de Prueba**: Ejecuta múltiples casos predefinidos
- 📊 **Resultados Detallados**: Muestra el mapeo completo con códigos y nombres
- ✅ **Indicadores de Éxito/Error**: Visual feedback del resultado

### Casos de Prueba Predefinidos

```php
['marca' => 'TOYOTA', 'modelo' => 'FJ CRUISER'],
['marca' => 'TOYOTA', 'modelo' => 'FJ CRUISER TRAIL TEAM'],
['marca' => 'TOYOTA', 'modelo' => 'FJ CRUISER TRD'],
['marca' => 'TOYOTA', 'modelo' => 'FJ40LVN'],
['marca' => 'TOYOTA', 'modelo' => 'FJ40L']
```

## Logs

El mapper registra cada paso del proceso:

```
[VehicleMapper] Marca encontrada: TOYOTA -> 229
[VehicleMapper] Cargados 15 modelos para marca 229
[VehicleMapper] Modelo encontrado: FJ CRUISER -> 229|11
[VehicleMapper] Cargadas 3 versiones para modelo 229|11
[VehicleMapper] Versión encontrada: FJ CRUISER TRAIL TEAM -> 229|11|2
```

## Mantenimiento

### Agregar Nuevos Patrones de Versión

Edita el método `extractModeloBase()` en `VehicleMapper.php`:

```php
$patronesVersion = [
    ' TRAIL TEAM',
    ' TRD',
    ' TU_NUEVO_PATRON',  // Agregar aquí
    // ...
];
```

### Ajustar Similitud Mínima

En el método `findVersion()`, ajusta el umbral:

```php
if ($maxSimilitud >= 70) {  // Cambiar este valor (0-100)
    return $mejorMatch;
}
```

## Troubleshooting

### El vehículo no se mapea correctamente

1. Verifica los logs en la base de datos
2. Usa la página de test para ver el mapeo paso a paso
3. Confirma que la marca existe en la API de Dominicana
4. Verifica que el modelo exista para esa marca

### Performance lento

- El mapper usa cache automáticamente
- Las llamadas a la API se minimizan
- Para limpiar cache: `$mapper->clearCache()`

### Fallback al método legacy

Si ves este warning en los logs:
```
VehicleMapper falló, usando método legacy
```

Revisa el error específico y ajusta el mapper según sea necesario.

## Arquitectura

```
MasterOne DB
    ↓
TransactionManager
    ↓
VehicleMapper
    ↓  (consulta marca, modelo, versión)
DominicanaAPI
    ↓
Dominicana de Seguros
```

## Archivos Relacionados

- `/classes/VehicleMapper.php` - Clase principal del mapper
- `/classes/TransactionManager.php` - Integración con el flujo de ventas
- `/admin/test_vehicle_mapper.php` - Página de testing
- `/classes/DominicanaAPI.php` - Cliente de la API

## Ventajas

✅ **Automático**: No requiere intervención manual
✅ **Inteligente**: Maneja múltiples formatos de modelo/versión
✅ **Robusto**: Fallback al método anterior si falla
✅ **Rápido**: Cache de resultados de API
✅ **Trazable**: Logging completo del proceso
✅ **Testeable**: Página dedicada para pruebas