# الملفات الناتجة

تتيح لك الملفات الناتجة تخزين مخرجات سير العمل الدائمة دون تضخيم حمولة حالة سير العمل الرئيسية.

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

## لماذا نستخدم الملفات الناتجة بدلًا من حالة سير العمل

تعد حالة سير العمل مثالية للبيانات العامة الصغيرة التي تحتاج إليها الخطوة التالية فورًا.

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

## خزّن ملفًا ناتجًا لخطوة سير العمل الحالية

عندما يكون الكود قيد التشغيل بالفعل داخل خطوة من سير العمل، استخدم `Queuety::put_current_artifact()`:

```php
use Queuety\Queuety;
use Queuety\Step;

final class DraftBriefStep implements Step
{
    public function handle(array $state): array
    {
        $draft = [
            'title' => 'Pricing brief',
            'body' => '...',
        ];

        Queuety::put_current_artifact(
            'draft',
            $draft,
            'json',
            [ 'source' => 'planner' ],
        );

        return [ 'draft_ready' => true ];
    }

    public function config(): array
    {
        return [];
    }
}
```

يرفق Queuety معرّف سير العمل الحالي ورقم الخطوة تلقائيًا.

## خزّن ملفًا ناتجًا من خارج سير العمل

إذا كنت تعرف معرّف سير العمل بالفعل، فاستخدم `Queuety::put_artifact()`:

```php
Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    "# Research Brief\n\nDone.",
    'markdown',
    metadata: [ 'reviewed_by' => 'editor@example.com' ],
);
```

## اقرأ الملفات الناتجة مجددًا

```php
$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );

$artifacts = Queuety::workflow_artifacts( $workflow_id );
```

يتضمن كل سجل ملف ناتج حقول `key` و`kind` و`content` و`metadata` و`step_index` و`created_at` و`updated_at`. ولا يعرض `Queuety::workflow_artifacts()` قيمة `content` إلا إذا مررت `true` بوصفه وسيطها الثاني.

## تكامل حالة سير العمل

يتضمن `Queuety::workflow_status()` الآن ملخصًا صغيرًا للملفات الناتجة:

```php
$status = Queuety::workflow_status( $workflow_id );

echo $status->artifact_count; // 2
print_r( $status->artifact_keys ); // ['draft', 'citations']
```

وهذا يُبقي العناصر المصطنعة ظاهرة من دون تضمين محتواها الكامل في مخرجات الحالة.

## CLI

اعرض عناصر سير العمل:

```bash
wp queuety workflow artifacts 42
```

اعرض عنصرًا واحدًا مع محتواه:

```bash
wp queuety workflow artifact 42 draft
```

راجع [CLI](https://queuety.inline0.dev/ar/docs/cli) للاطلاع على مرجع الأوامر الكامل.

## التصدير وإعادة التشغيل

تُضمّن العناصر المصطنعة في صادرات سير العمل وتُنسخ إلى مسارات العمل المُعاد تشغيلها.

وهذا يعني أن عمليات الوكلاء التي تعتمد على العناصر المصطنعة تظل قابلة للفحص حتى عند نقلها بين البيئات أو إعادة إنشاء تشغيل من سجل التنفيذ المُصدّر.