# السفر عبر الزمن في سير العمل

يمكن لـ Queuety إعادة سير العمل إلى خطوة سابقة واستئناف التنفيذ من تلك النقطة. يفيد ذلك عندما تنتج خطوة مخرجات غير صحيحة، أو عندما تريد إعادة المحاولة بإعدادات مختلفة، أو عندما تحتاج إلى استعادة البيانات التالفة من دون إعادة تشغيل سير العمل بأكمله.

تعتمد الإعادة على [سجل أحداث سير العمل](https://queuety.inline0.dev/ar/docs/workflows/event-log). يجب أن يحتوي سجل الأحداث على بيانات `state_after` للخطوة المستهدفة.

## إعادة سير العمل إلى خطوة سابقة

### PHP API

استدعِ `Queuety::rewind_workflow()` مع معرّف سير العمل وفهرس الخطوة المراد الرجوع إليها:

```php
use Queuety\Queuety;

// Rewind workflow 42 to step 1.
// The state is restored to the snapshot taken after step 1 completed,
// and step 2 is enqueued for re-execution.
Queuety::rewind_workflow( $workflow_id, to_step: 1 );
```

المعامل `to_step` هو فهرس يبدأ من الصفر للخطوة التي ينبغي استعادة حالتها المكتملة. يُستأنف التنفيذ من الخطوة التالية (to_step + 1).

### CLI

```bash
wp queuety workflow rewind <id> <step>
```

| الخيار | الوصف |
|---|---|
| `<id>` | معرّف سير العمل (مطلوب) |
| `<step>` | فهرس الخطوة المراد الرجوع إليها، يبدأ العد من 0 (مطلوب) |

```bash
wp queuety workflow rewind 42 1
```

## طريقة العمل

عند إعادة سير العمل إلى الخطوة N:

1. يُستعلم من سجل الأحداث عن قيمة `state_after` المسجلة بعد اكتمال الخطوة N
2. إذا لم توجد لقطة، فسيُطلق `RuntimeException`
3. يُقفل صف سير العمل
4. تُستبدل حالة سير العمل باللقطة، مع الحفاظ على جميع المفاتيح المحجوزة (`_steps` و`_queue` و`_priority` وما إلى ذلك) من صف سير العمل الحالي
5. تُضبط `current_step` على N + 1 وتُضبط `status` على `running`
6. تُمسح أي حقول `error_message` و`failed_at`
7. تُدرج الخطوة ذات الفهرس N + 1 في قائمة انتظار المعالجة
8. يُسجل حدث `workflow_rewound` في السجل

بعد ذلك، يتولى العامل الخطوة المدرجة في قائمة الانتظار ويواصل سير العمل كالمعتاد من تلك النقطة فصاعدًا.

## المتطلبات

تتطلب الإعادة بيانات `state_after` في سجل الأحداث. يسجلها سجل الأحداث تلقائيًا لكل حدث `step_completed`. إذا جرى تنقيح سجل الأحداث (عبر `WorkflowEventLog::prune()`) ولم تعد حالة الخطوة المستهدفة موجودة، فستفشل الإعادة.

تأكد من أن مدة الاحتفاظ بسجل الأحداث تغطي الفترة التي قد تحتاج إلى الرجوع إليها.

## حالات الاستخدام

### إصلاح معالج خطوة معيب

إذا احتوى معالج خطوة على خطأ أنتج مخرجات غير صحيحة، فيمكنك نشر الإصلاح ثم إعادة سير العمل:

```php
// Step 2 (CallLLMHandler) produced garbled output due to a prompt bug.
// After fixing CallLLMHandler, rewind to step 1 so step 2 runs again
// with the corrected handler.
Queuety::rewind_workflow( $workflow_id, to_step: 1 );
```

### إعادة المحاولة بإعدادات مختلفة

عندما تفشل خطوة بسبب عوامل خارجية (API حد لمعدل الطلبات، أو بيانات اعتماد غير صحيحة)، أصلح الإعدادات وأعِد سير العمل لتشغيلها مجددًا:

```php
// Step 3 failed because the API key was expired.
// After updating the key, rewind to step 2 so step 3 retries.
Queuety::rewind_workflow( $workflow_id, to_step: 2 );
```

### استعادة البيانات غير الصحيحة

إذا أدخلت خطوة سابقة بيانات غير صحيحة إلى الحالة، فأعِد سير العمل إلى لقطة معروفة بصحتها:

```php
// Step 0 fetched correct data, but step 1 corrupted it.
// Rewind to step 0 to restore the good state and re-run step 1.
Queuety::rewind_workflow( $workflow_id, to_step: 0 );
```

## مقارنة بإعادة المحاولة

| الجانب | `retry_workflow()` | `rewind_workflow()` |
|---|---|---|
| نقطة الاستئناف | الخطوة الفاشلة | أي خطوة سابقة |
| الحالة | حالة سير العمل الحالية | مستعادة من لقطة سجل الأحداث `state_after` |
| المتطلبات | أن تكون حالة سير العمل `failed` | لقطة في سجل الأحداث عند الخطوة المستهدفة |
| الحالة بعد الإجراء | `running` | `running` |
| حدث السجل | لا يوجد | `workflow_rewound` |