# Gestione dei conflitti

Si verifica un conflitto quando i due lati di un’unione modificano gli stessi dati in modi incompatibili. merql rileva quattro tipi di conflitto e offre strategie di risoluzione automatiche e manuali.

```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";
    }
}
```

## Tipi di conflitto

### update_update

Entrambi i lati hanno modificato la stessa colonna della stessa riga con valori diversi. È il tipo di conflitto più comune.

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

Il conflitto segnala: tabella `posts`, chiave della riga `42`, colonna `title`, valore nostro `Welcome`, valore altrui `Greetings`, valore di base `Hello`.

### update_delete

Un lato ha aggiornato una riga, l’altro l’ha eliminata. merql non può stabilire se debba prevalere l’aggiornamento o l’eliminazione.

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

Il conflitto segnala: tabella `posts`, chiave della riga `42`, tipo `update_delete`. Il valore nostro contiene la riga aggiornata completa. Il valore altrui è `null`.

### delete_update

Il contrario di update_delete. L’altro lato ha aggiornato la riga, noi l’abbiamo eliminata.

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

Il conflitto segnala: tipo `delete_update`. Il valore nostro è `null`, il valore altrui contiene la riga aggiornata completa.

### insert_insert

Entrambi i lati hanno inserito una riga con la stessa chiave primaria. Poiché entrambe le righe sono nuove (non presenti nella base), merql non può unirle.

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

Il conflitto segnala: tipo `insert_insert`. Il valore nostro contiene i dati della nostra riga, il valore altrui contiene i dati della riga altrui.

## La classe Conflict

Ogni conflitto è un oggetto di sola lettura con questi accessor:

```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)
```

Il metodo `column()` restituisce il nome di una colonna per i conflitti `update_update` e `null` per i conflitti strutturali (`update_delete`, `delete_update`, `insert_insert`).

### Decodificare la chiave primaria

La chiave della riga è una stringa codificata. Per ottenere un array delle chiavi primarie con i nomi, passate le colonne di identità:

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

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

## Risoluzione automatica con ConflictPolicy

`ConflictResolver` applica un criterio per risolvere tutti i conflitti in una volta:

```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);
```

### Enum ConflictPolicy

| Valore | Comportamento |
|---|---|
| `OursWins` | Usa il valore nostro per update_update. Mantiene l’aggiornamento per update_delete. Mantiene l’eliminazione per delete_update. Usa il nostro inserimento per insert_insert. |
| `TheirsWins` | Usa il valore altrui per update_update. Elimina per update_delete. Mantiene l’aggiornamento per delete_update. Usa l’inserimento altrui per insert_insert. |
| `Manual` | Restituisce il risultato invariato. Tutti i conflitti restano irrisolti. |

### Come funziona la risoluzione

Per i conflitti `update_update`, il resolver modifica l’operazione di unione esistente per quella riga, sostituendo il valore della colonna in conflitto con quello del lato vincente.

Per i conflitti strutturali (`update_delete`, `delete_update`, `insert_insert`), il resolver aggiunge una nuova operazione al risultato:

- `update_delete` con `OursWins` aggiunge un’operazione UPDATE.
- `update_delete` con `TheirsWins` aggiunge un’operazione DELETE.
- `delete_update` con `OursWins` aggiunge un’operazione DELETE.
- `delete_update` con `TheirsWins` aggiunge un’operazione UPDATE.
- `insert_insert` usa i valori della riga del lato vincente.

Il risultato `MergeResult` risolto ha un elenco dei conflitti vuoto e può essere applicato direttamente.

## Risoluzione manuale

Per un controllo più preciso, esaminate ogni conflitto e create la vostra risoluzione:

```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";
    }
}
```

## Applicazione con conflitti irrisolti

`Applier` rifiuta di applicare un risultato di unione con conflitti irrisolti. Lancia un `ConflictException`:

```php
use Merql\Exceptions\ConflictException;

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

Risolvi sempre i conflitti prima di applicare il risultato, usando `ConflictResolver::resolve()` oppure creando manualmente un `MergeResult` senza conflitti.