# Gestión de conflictos

Se produce un conflicto cuando ambas partes de una combinación modifican los mismos datos de formas incompatibles. merql detecta cuatro tipos de conflictos y ofrece estrategias de resolución automáticas y manuales.

```php
$result = $merge->merge($base, $ours, $theirs);

if (!$result->isClean()) {
    foreach ($result->conflicts() as $conflict) {
        echo "{$conflict->table()}.{$conflict->column()}: "
           . "{$conflict->oursValue()} vs {$conflict->theirsValue()}\n";
    }
}
```

## Tipos de conflicto

### update_update

Ambas partes cambiaron la misma columna de la misma fila con valores distintos. Es el tipo de conflicto más común.

```
Base:    posts #42  title = "Hello"
Ours:    posts #42  title = "Welcome"
Theirs:  posts #42  title = "Greetings"
```

El conflicto informa de: tabla `posts`, clave de fila `42`, columna `title`, valor de nuestro lado `Welcome`, valor del suyo `Greetings` y valor base `Hello`.

### update_delete

Una parte actualizó una fila y la otra la eliminó. merql no puede determinar qué debe prevalecer, si la actualización o la eliminación.

```
Ours:    posts #42  title = "Updated Title"    (updated)
Theirs:  posts #42  (deleted)
```

El conflicto informa de: tabla `posts`, clave de fila `42` y tipo `update_delete`. El valor de nuestro lado contiene la fila completa actualizada. El valor del suyo es `null`.

### delete_update

Lo contrario de update_delete. El suyo actualizó la fila y el nuestro la eliminó.

```
Ours:    posts #42  (deleted)
Theirs:  posts #42  title = "Updated Title"    (updated)
```

El conflicto informa del tipo `delete_update`. El valor de nuestro lado es `null`; el del suyo contiene la fila completa actualizada.

### insert_insert

Ambas partes insertaron una fila con la misma clave principal. Como ambas filas son nuevas (no existían en la base), merql no puede combinarlas.

```
Base:    (no row #99)
Ours:    posts #99  { title: "My Post" }
Theirs:  posts #99  { title: "Their Post" }
```

El conflicto informa del tipo `insert_insert`. El valor de nuestro lado contiene los datos de nuestra fila y el del suyo contiene los de su fila.

## La clase Conflict

Cada conflicto es un objeto de solo lectura con estos accesores:

```php
$conflict->table();      // string: table name
$conflict->rowKey();     // string: encoded row identity key
$conflict->type();       // string: "update_update"|"update_delete"|"delete_update"|"insert_insert"
$conflict->column();     // ?string: column name (null for structural conflicts)
$conflict->oursValue();  // mixed: our value (null for delete side, full row for structural)
$conflict->theirsValue(); // mixed: their value (null for delete side, full row for structural)
$conflict->baseValue();  // mixed: base value (null for inserts)
```

El método `column()` devuelve un nombre de columna en conflictos `update_update` y `null` en conflictos estructurales (`update_delete`, `delete_update`, `insert_insert`).

### Decodificar la clave principal

La clave de fila es una cadena codificada. Para obtener una matriz de claves principales con nombre, pase las columnas de identidad:

```php
$pk = $conflict->primaryKey(['id']);
// ['id' => '42']

$pk = $conflict->primaryKey(['tenant_id', 'user_id']);
// ['tenant_id' => '1', 'user_id' => '99']
```

## Resolución automática con ConflictPolicy

`ConflictResolver` aplica una política para resolver todos los conflictos a la vez:

```php
use Merql\Merge\ConflictPolicy;
use Merql\Merge\ConflictResolver;

// One side wins everywhere.
$resolved = ConflictResolver::resolve($result, ConflictPolicy::OursWins);
$resolved = ConflictResolver::resolve($result, ConflictPolicy::TheirsWins);

// Manual: return the result unchanged (inspect conflicts yourself).
$resolved = ConflictResolver::resolve($result, ConflictPolicy::Manual);
```

### Enumeración ConflictPolicy

| Valor | Comportamiento |
|---|---|
| `OursWins` | Usar nuestro valor en update_update. Conservar la actualización en update_delete. Conservar la eliminación en delete_update. Usar nuestra inserción en insert_insert. |
| `TheirsWins` | Usar el valor del suyo en update_update. Eliminar en update_delete. Conservar la actualización en delete_update. Usar su inserción en insert_insert. |
| `Manual` | Devolver el resultado sin cambios. Todos los conflictos quedan sin resolver. |

### Cómo funciona la resolución

Para conflictos `update_update`, el solucionador modifica la operación de combinación existente para esa fila y reemplaza el valor de la columna en conflicto por el valor de la parte ganadora.

Para conflictos estructurales (`update_delete`, `delete_update`, `insert_insert`), el solucionador añade una operación nueva al resultado:

- `update_delete` con `OursWins` añade una operación UPDATE.
- `update_delete` con `TheirsWins` añade una operación DELETE.
- `delete_update` con `OursWins` añade una operación DELETE.
- `delete_update` con `TheirsWins` añade una operación UPDATE.
- `insert_insert` usa los valores de fila de la parte ganadora.

El `MergeResult` resuelto tiene una lista de conflictos vacía y se puede aplicar directamente.

## Resolución manual

Para un control más preciso, inspeccione cada conflicto y cree su propia resolución:

```php
foreach ($result->conflicts() as $conflict) {
    echo "Table:  {$conflict->table()}\n";
    echo "Row:    {$conflict->rowKey()}\n";
    echo "Type:   {$conflict->type()}\n";

    if ($conflict->column() !== null) {
        echo "Column: {$conflict->column()}\n";
        echo "Base:   " . var_export($conflict->baseValue(), true) . "\n";
        echo "Ours:   " . var_export($conflict->oursValue(), true) . "\n";
        echo "Theirs: " . var_export($conflict->theirsValue(), true) . "\n";
    }
}
```

## Aplicar con conflictos sin resolver

`Applier` se niega a aplicar un resultado de combinación con conflictos sin resolver. Lanza un `ConflictException`:

```php
use Merql\Exceptions\ConflictException;

try {
    $applier->apply($result);
} catch (ConflictException $e) {
    echo $e->getMessage();
    // "Cannot apply merge with 3 unresolved conflicts"
}
```

Resuelva siempre los conflictos antes de aplicar, ya sea con `ConflictResolver::resolve()` o creando manualmente un `MergeResult` limpio.