# معالجة التعارضات

يحدث التعارض عندما يغيّر طرفا الدمج البيانات نفسها بطرق غير متوافقة. يكتشف 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`، و`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` | استخدام قيمة ours في update_update. الإبقاء على التحديث في update_delete. الإبقاء على الحذف في delete_update. استخدام إدراج ours في insert_insert. |
| `TheirsWins` | استخدام قيمة theirs في update_update. الحذف في update_delete. الإبقاء على التحديث في delete_update. استخدام إدراج theirs في 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` نظيف يدويًا.