# Como lidar com conflitos

Ocorre um conflito quando os dois lados de uma mesclagem alteram os mesmos dados de maneiras incompatíveis. merql detecta quatro tipos de conflito e oferece estratégias de resolução automáticas e manuais.

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

### update_update

Os dois lados alteraram a mesma coluna da mesma linha para valores diferentes. Esse é o tipo de conflito mais comum.

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

O conflito informa: tabela `posts`, chave da linha `42`, coluna `title`, valor de nosso `Welcome`, valor de deles `Greetings`, valor da base `Hello`.

### update_delete

Um lado atualizou uma linha e o outro a excluiu. merql não consegue determinar se a atualização ou a exclusão deve prevalecer.

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

O conflito informa: tabela `posts`, chave da linha `42`, tipo `update_delete`. O valor de ours contém a linha atualizada completa. O valor de theirs é `null`.

### delete_update

O inverso de update_delete. Theirs atualizou a linha, ours a excluiu.

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

O conflito informa: tipo `delete_update`. O valor de ours é `null`, e o valor de theirs contém a linha atualizada completa.

### insert_insert

Ambos os lados inseriram uma linha com a mesma chave primária. Como as duas linhas são novas (não estavam presentes na base), merql não consegue mesclá-las.

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

O conflito informa: tipo `insert_insert`. O valor de ours contém os dados da linha de ours, e o valor de theirs contém os dados da linha de theirs.

## A classe Conflict

Cada conflito é um objeto somente para leitura com estes acessores:

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

O método `column()` retorna o nome de uma coluna para conflitos `update_update` e `null` para conflitos estruturais (`update_delete`, `delete_update`, `insert_insert`).

### Decodificando a chave primária

A chave da linha é uma string codificada. Para obter um array com os nomes das colunas da chave primária, passe as colunas de identidade:

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

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

## Resolução automática com ConflictPolicy

O `ConflictResolver` aplica uma política para resolver todos os conflitos de uma só 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);
```

### Enum ConflictPolicy

| Valor | Comportamento |
|---|---|
| `OursWins` | Usa o valor de ours para update_update. Mantém a atualização para update_delete. Mantém a exclusão para delete_update. Usa a inserção de ours para insert_insert. |
| `TheirsWins` | Usa o valor de theirs para update_update. Exclui para update_delete. Mantém a atualização para delete_update. Usa a inserção de theirs para insert_insert. |
| `Manual` | Retorna o resultado sem alterações. Todos os conflitos permanecem sem resolução. |

### Como funciona a resolução

Para conflitos `update_update`, o resolvedor corrige a operação de mesclagem existente para essa linha, substituindo o valor da coluna em conflito pelo valor do lado vencedor.

Para conflitos estruturais (`update_delete`, `delete_update`, `insert_insert`), o resolvedor adiciona uma nova operação ao resultado:

- `update_delete` com `OursWins` adiciona uma operação UPDATE.
- `update_delete` com `TheirsWins` adiciona uma operação DELETE.
- `delete_update` com `OursWins` adiciona uma operação DELETE.
- `delete_update` com `TheirsWins` adiciona uma operação UPDATE.
- `insert_insert` usa os valores de linha do lado vencedor.

O `MergeResult` resolvido tem uma lista de conflitos vazia e pode ser aplicado diretamente.

## Resolução manual

Para ter um controle mais preciso, examine cada conflito e crie sua própria resolução:

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

## Aplicação com conflitos não resolvidos

O `Applier` se recusa a aplicar um resultado de mesclagem que tenha conflitos não resolvidos. Ele lança um `ConflictException`:

```php
use Merql\Exceptions\ConflictException;

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

Sempre resolva os conflitos antes de aplicar, usando `ConflictResolver::resolve()` ou criando manualmente um `MergeResult` sem conflitos.