# Обробка конфліктів

Конфлікт виникає, коли обидві сторони злиття змінюють ті самі дані несумісним чином. merql виявляє чотири типи конфліктів і пропонує стратегії автоматичного та ручного розв’язання.

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

## Типи конфліктів

### update_update

Обидві сторони змінили той самий стовпець того самого рядка на різні значення. Це найпоширеніший тип конфлікту.

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

У звіті про конфлікт зазначено: таблиця `posts`, ключ рядка `42`, стовпець `title`, наше значення `Welcome`, їхнє значення `Greetings`, базове значення `Hello`.

### update_delete

Одна сторона оновила рядок, а інша видалила його. merql не може визначити, що має перемогти: оновлення чи видалення.

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

У звіті про конфлікт зазначено: таблиця `posts`, ключ рядка `42`, тип `update_delete`. Наше значення містить повністю оновлений рядок. Їхнє значення — `null`.

### delete_update

Зворотна ситуація для update_delete. Їхня сторона оновила рядок, а наша — видалила його.

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

У звіті про конфлікт зазначено: тип `delete_update`. Наше значення — `null`, а їхнє містить повністю оновлений рядок.

### insert_insert

Обидві сторони вставили рядок з однаковим первинним ключем. Оскільки обидва рядки нові (їх не було в базі), merql не може їх об’єднати.

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

У звіті про конфлікт зазначено: тип `insert_insert`. Наше значення містить дані нашого рядка, а їхнє — дані їхнього рядка.

## Клас Conflict

Кожен конфлікт — це об’єкт лише для читання з такими методами доступу:

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

Метод `column()` повертає назву стовпця для конфліктів `update_update` і `null` для структурних конфліктів (`update_delete`, `delete_update`, `insert_insert`).

### Декодування первинного ключа

Ключ рядка — це закодований рядок. Щоб отримати масив іменованих первинних ключів, передайте стовпці ідентифікації:

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

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

## Автоматичне розв’язання за допомогою ConflictPolicy

`ConflictResolver` застосовує політику до всіх конфліктів одночасно:

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

### Перелік ConflictPolicy

| Значення | Поведінка |
|---|---|
| `OursWins` | Для update_update використовувати наше значення. Для update_delete залишити оновлення. Для delete_update залишити видалення. Для insert_insert використовувати нашу вставку. |
| `TheirsWins` | Для update_update використовувати їхнє значення. Для update_delete видалити. Для delete_update залишити оновлення. Для insert_insert використовувати їхню вставку. |
| `Manual` | Повернути результат без змін. Усі конфлікти залишаються нерозв’язаними. |

### Як відбувається розв’язання

Для конфліктів `update_update` засіб розв’язання змінює наявну операцію злиття для цього рядка, замінюючи значення конфліктного стовпця значенням сторони-переможця.

Для структурних конфліктів (`update_delete`, `delete_update`, `insert_insert`) засіб розв’язання додає до результату нову операцію:

- `update_delete` з `OursWins` додає операцію UPDATE.
- `update_delete` з `TheirsWins` додає операцію DELETE.
- `delete_update` з `OursWins` додає операцію DELETE.
- `delete_update` з `TheirsWins` додає операцію UPDATE.
- Для `insert_insert` використовуються значення рядка сторони-переможця.

Розв’язаний `MergeResult` має порожній список конфліктів і готовий до застосування.

## Ручне розв’язання

Для точного контролю перегляньте кожен конфлікт і створіть власне розв’язання:

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

## Застосування за наявності нерозв’язаних конфліктів

`Applier` відмовляється застосовувати результат злиття з нерозв’язаними конфліктами. Він викидає `ConflictException`:

```php
use Merql\Exceptions\ConflictException;

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

Завжди розв’язуйте конфлікти перед застосуванням: за допомогою `ConflictResolver::resolve()` або створивши чистий `MergeResult` вручну.