# سجل أحداث سيرورة العمل

يسجل سجل أحداث سيرورة العمل أثرًا لكل حد دائم في سيرورة العمل. ويمكن أن يتضمن كل حدث في الأثر مدخلات الخطوة ومخرجاتها والحالة العامة قبل الخطوة وبعدها وسياق وقت التشغيل ومراجع الملفات المرفقة والأجزاء المتدفقة والتوقيت وتفاصيل الأخطاء.

## البيانات المسجلة

| الحدث | التوقيت | البيانات الملتقطة |
|---|---|---|
| `step_started` | قبل تشغيل معالج الخطوة | معرّف المهمة، وقائمة الانتظار، والمحاولة، واسم الخطوة، ونوعها، والمدخلات، والحالة قبل التنفيذ |
| `step_completed` | بعد نجاح معالج الخطوة | المدخلات، والمخرجات، والحالة قبل التنفيذ، والحالة بعده، والسياق، والملفات المرفقة، والأجزاء، والمدة |
| `step_failed` | عند طرح معالج الخطوة استثناءً | المدخلات، والحالة قبل التنفيذ، والحالة بعده عند توفرها، والسياق، وفئة الخطأ، ورسالة الخطأ، والتتبّع، والمدة |
| `step_branch_completed` | عند نجاح أحد الفروع المتوازية | مدخلات الفرع، ومخرجاته، والحالة قبل التنفيذ، والحالة بعده، والسياق، والمدة |
| `step_item_completed` | عند نجاح أحد عناصر التكرار على كل عنصر | مدخلات العنصر، ومخرجاته، والحالة قبل التنفيذ، والحالة بعده، وبيانات العنصر الوصفية، والسياق، والمدة |
| `workflow_waiting` | عندما توقف خطوة انتظار التنفيذ مؤقتًا | نوع الانتظار، وأهدافه، ونمطه، ومفتاح النتيجة، وبيانات المطابقة الوصفية، والحالة أثناء الانتظار |
| `workflow_resumed` | عند استيفاء شرط خطوة الانتظار | حمولة الاستئناف، والحالة قبل الاستئناف، والحالة بعده |
| `workflow_replayed` | عند إعادة إنشاء عملية تصدير | بيانات سيرورة العمل المصدر الوصفية وحالة إعادة التشغيل |

## الاستعلام عن الخط الزمني

```php
$events = Queuety::workflow_timeline( $workflow_id );

foreach ( $events as $event ) {
    echo $event['step_index'] . ' ' . $event['event'] . ' ' . $event['handler'] . "\n";

    if ( 'step_completed' === $event['event'] ) {
        $input        = $event['input'];
        $output       = $event['output'];
        $state_before = $event['state_before'];
        $state_after  = $event['state_after'];
    }

    if ( 'step_failed' === $event['event'] ) {
        echo 'Error: ' . $event['error']['message'] . "\n";
    }
}
```

يحتوي كل صف حدث على:

- `id`
- `workflow_id`
- `job_id`
- `parent_event_id`
- `step_index`
- `step_name`
- `step_type`
- `handler`
- `event`
- `queue`
- `attempt`
- `input`
- `output`
- `state_before`
- `state_after`
- `context`
- `artifacts`
- `chunks`
- `error`
- `duration_ms`
- `created_at`

## حزمة الأثر الموحّدة

استخدم `workflow_trace()` عند إنشاء أداة تصحيح أخطاء UI:

```php
$trace = Queuety::workflow_trace( $workflow_id );
```

تتضمن حزمة الأثر ما يلي:

- `workflow`
- `steps`
- `events`
- `jobs`
- `logs`
- `artifacts`
- `chunks`
- `signals`
- `wait_dependencies`

تجمع `steps` الأحداث حسب فهرس الخطوة، وتتضمن أحدث حدث مهم لكل خطوة.

## البحث عن حالة الخطوة

```php
$state = Queuety::workflow_state_at( $workflow_id, $step_index );
```

يعيد هذا الحالة العامة `state_after` من أحدث حدث مكتمل أو مستأنف لتلك الخطوة، أو `null` إذا لم تُسجل أي حالة.

## بيانات تتبّع وقت التشغيل الوصفية

يمكن للمعالجات إضافة تفاصيل تتبّع على مستوى التطبيق أثناء عملها:

```php
Queuety::trace_input( [ 'resolved' => $resolved_input ] );
Queuety::trace_context( [ 'ability' => 'content/load-post' ] );
Queuety::trace_output( [ 'post' => $post ] );
```

يمكن لمعالجات الخطوات أيضًا إرجاع بيانات تتبّع وصفية محجوزة:

```php
return [
    'result' => 'done',
    '_queuety_trace' => [
        'input' => [ 'resolved' => $resolved_input ],
        'context' => [ 'node_id' => 'loadPost' ],
        'artifacts' => [
            [ 'key' => 'brief', 'kind' => 'markdown' ],
        ],
    ],
];
```

يُخزن المفتاح `_queuety_trace` في سجل الأحداث ولا يُدمج في حالة سيرورة العمل.

## CLI

اعرض الخط الزمني كجدول:

```bash
wp queuety workflow timeline 42
```

اعرض الحالة بعد خطوة:

```bash
wp queuety workflow state-at 42 0
```

## الاحتفاظ

تتراكم سجلات الأحداث بمرور الوقت. استخدم `prune()` لحذف أحداث الأثر القديمة:

```php
$deleted = Queuety::workflow_events()->prune( 30 );
```