# 충돌 처리

병합 양쪽에서 같은 데이터를 호환되지 않는 방식으로 변경하면 충돌이 발생합니다. 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`, ours 값 `Welcome`, theirs 값 `Greetings`, 기준값 `Hello`.

### update_delete

한쪽은 행을 업데이트하고 다른 쪽은 삭제했습니다. merql은 업데이트와 삭제 중 어느 쪽을 적용해야 할지 판단할 수 없습니다.

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

충돌에는 다음이 보고됩니다. 테이블 `posts`, 행 키 `42`, 유형 `update_delete`. ours 값에는 업데이트된 행 전체가 들어 있습니다. theirs 값은 `null`입니다.

### delete_update

update_delete의 반대 경우입니다. theirs는 행을 업데이트하고 ours는 삭제했습니다.

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

충돌에는 유형 `delete_update`이 보고됩니다. ours 값은 `null`이고 theirs 값에는 업데이트된 행 전체가 들어 있습니다.

### insert_insert

양쪽에서 같은 기본 키로 행을 삽입했습니다. 두 행 모두 새 행이고 기준 상태에 없으므로 merql은 병합할 수 없습니다.

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

충돌 유형 `insert_insert`이 보고됩니다. ours 값에는 ours 행 데이터가, theirs 값에는 theirs 행 데이터가 들어 있습니다.

## 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` 충돌의 열 이름을 반환하고, 구조적 충돌(`update_delete`, `delete_update`, `insert_insert`)에는 `null`를 반환합니다.

### 기본 키 디코딩

행 키는 인코딩된 문자열입니다. 이름이 지정된 기본 키 배열을 얻으려면 식별 열을 전달하세요.

```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에는 ours 값을 사용합니다. update_delete에서는 업데이트를 유지합니다. delete_update에서는 삭제를 유지합니다. insert_insert에는 ours 삽입을 사용합니다. |
| `TheirsWins` | update_update에는 theirs 값을 사용합니다. update_delete에서는 삭제합니다. delete_update에서는 업데이트를 유지합니다. insert_insert에는 theirs 삽입을 사용합니다. |
| `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`을 구성해 충돌을 해결하세요.