# Obsługa konfliktów

Konflikt występuje, gdy obie strony scalania zmieniają te same dane w niezgodny sposób. merql wykrywa cztery typy konfliktów i udostępnia automatyczne oraz ręczne strategie ich rozwiązywania.

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

## Typy konfliktów

### update_update

Obie strony zmieniły tę samą kolumnę w tym samym wierszu na różne wartości. To najczęstszy typ konfliktu.

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

Konflikt zawiera: tabelę `posts`, klucz wiersza `42`, kolumnę `title`, naszą wartość `Welcome`, wartość drugiej strony `Greetings` i wartość bazową `Hello`.

### update_delete

Jedna strona zaktualizowała wiersz, a druga go usunęła. merql nie może ustalić, czy powinna wygrać aktualizacja, czy usunięcie.

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

Konflikt zawiera: tabelę `posts`, klucz wiersza `42` i typ `update_delete`. Nasza wartość zawiera cały zaktualizowany wiersz. Wartość drugiej strony to `null`.

### delete_update

Odwrotność update_delete. Druga strona zaktualizowała wiersz, a nasza go usunęła.

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

Konflikt zawiera: typ `delete_update`. Nasza wartość to `null`, a wartość drugiej strony zawiera cały zaktualizowany wiersz.

### insert_insert

Obie strony wstawiły wiersz z tym samym kluczem głównym. Ponieważ oba wiersze są nowe (nie występują w bazie), merql nie może ich scalić.

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

Konflikt zawiera: typ `insert_insert`. Nasza wartość zawiera dane naszego wiersza, a wartość drugiej strony — dane jej wiersza.

## Klasa Conflict

Każdy konflikt jest obiektem tylko do odczytu z następującymi akcesorami:

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

Metoda `column()` zwraca nazwę kolumny dla konfliktów `update_update`, a `null` dla konfliktów strukturalnych (`update_delete`, `delete_update`, `insert_insert`).

### Odczytywanie klucza głównego

Klucz wiersza jest zakodowanym ciągiem. Aby uzyskać tablicę z nazwami kluczy głównych, przekaż kolumny tożsamości:

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

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

## Automatyczne rozwiązywanie za pomocą ConflictPolicy

`ConflictResolver` stosuje zasady, aby rozwiązać wszystkie konflikty jednocześnie:

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

### Wyliczenie ConflictPolicy

| Wartość | Działanie |
|---|---|
| `OursWins` | W przypadku update_update używa naszej wartości. W przypadku update_delete zachowuje aktualizację. W przypadku delete_update zachowuje usunięcie. W przypadku insert_insert używa naszego wstawienia. |
| `TheirsWins` | W przypadku update_update używa wartości drugiej strony. W przypadku update_delete usuwa. W przypadku delete_update zachowuje aktualizację. W przypadku insert_insert używa wstawienia drugiej strony. |
| `Manual` | Zwraca wynik bez zmian. Wszystkie konflikty pozostają nierozwiązane. |

### Jak działa rozwiązywanie

W przypadku konfliktów `update_update` mechanizm rozwiązywania modyfikuje istniejącą operację scalania dla danego wiersza, zastępując wartość konfliktowej kolumny wartością wygrywającej strony.

W przypadku konfliktów strukturalnych (`update_delete`, `delete_update`, `insert_insert`) mechanizm rozwiązywania dodaje do wyniku nową operację:

- `update_delete` z `OursWins` dodaje operację UPDATE.
- `update_delete` z `TheirsWins` dodaje operację DELETE.
- `delete_update` z `OursWins` dodaje operację DELETE.
- `delete_update` z `TheirsWins` dodaje operację UPDATE.
- `insert_insert` używa wartości wiersza ze zwycięskiej strony.

Rozwiązany obiekt `MergeResult` ma pustą listę konfliktów i można go zastosować bezpośrednio.

## Ręczne rozwiązywanie

Aby uzyskać szczegółową kontrolę, sprawdź każdy konflikt i przygotuj własne rozwiązanie:

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

## Zastosowanie przy nierozwiązanych konfliktach

`Applier` odmawia zastosowania wyniku scalania z nierozwiązanymi konfliktami. Zgłasza wyjątek `ConflictException`:

```php
use Merql\Exceptions\ConflictException;

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

Zawsze rozwiązuj konflikty przed zastosowaniem wyniku, używając `ConflictResolver::resolve()` albo ręcznie tworząc czysty obiekt `MergeResult`.