# قوالب سير العمل

تتيح لك قوالب سير العمل تعريف بنية خطوات سير العمل مرة واحدة وإطلاقه عدة مرات بالاسم. ويفيد ذلك عندما تحتاج العملية نفسها متعددة الخطوات إلى العمل بحمولات مختلفة.

## تعريف قالب

استخدم `Queuety::define_workflow()` لإنشاء القالب، ثم سجّله:

```php
use Queuety\Queuety;
use Queuety\Enums\Priority;

$builder = Queuety::define_workflow( 'onboarding' )
    ->on_queue( 'pipelines' )
    ->with_priority( Priority::Normal )
    ->max_attempts( 5 )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class )
    ->then( NotifyAdminHandler::class );

Queuety::register_workflow_template( $builder );
```

سجّل القوالب مبكرًا، على سبيل المثال في خطاف التهيئة لأحد الإضافات:

```php
add_action( 'init', function () {
    $builder = Queuety::define_workflow( 'onboarding' )
        ->then( CreateAccountHandler::class )
        ->then( SendWelcomeEmailHandler::class )
        ->then( NotifyAdminHandler::class );

    Queuety::register_workflow_template( $builder );
} );
```

## تشغيل قالب

أطلق قالبًا مسجلًا باسمه باستخدام `Queuety::run_workflow()`:

```php
$workflow_id = Queuety::run_workflow( 'onboarding', [ 'email' => 'user@example.com' ] );
```

الوسيط الثاني هو الحمولة أو الحالة الأولية، تمامًا مثل `->dispatch()` في المنشئ. والعدد الصحيح المُعاد هو معرّف سير العمل.

إذا لم يكن القالب مسجلًا، فسيُطلق `RuntimeException`.

## عرض القوالب المسجلة

يمكنك الوصول إلى سجل القوالب:

```php
$registry = Queuety::workflow_templates();
$template = $registry->get( 'onboarding' ); // WorkflowTemplate or null
```

## مثال كامل

```php
// Register templates on init.
add_action( 'init', function () {
    // User onboarding pipeline
    $onboarding = Queuety::define_workflow( 'onboarding' )
        ->on_queue( 'users' )
        ->then( CreateAccountHandler::class )
        ->then( SetupDefaultsHandler::class )
        ->then( SendWelcomeEmailHandler::class );
    Queuety::register_workflow_template( $onboarding );

    // Content generation pipeline
    $content = Queuety::define_workflow( 'generate_content' )
        ->on_queue( 'llm' )
        ->max_attempts( 5 )
        ->then( BuildPromptHandler::class )
        ->then( CallLLMHandler::class )
        ->then( ReviewOutputHandler::class )
        ->then( PublishHandler::class );
    Queuety::register_workflow_template( $content );
} );

// Dispatch them anywhere in your application.
$wf1 = Queuety::run_workflow( 'onboarding', [ 'email' => 'alice@example.com' ] );
$wf2 = Queuety::run_workflow( 'generate_content', [ 'topic' => 'WordPress performance' ] );
```

## القوالب مقابل مهام سير العمل المضمنة

| | سير عمل مضمن | قالب |
|---|---|---|
| التعريف | وقت الإطلاق | مرة واحدة عند التسجيل |
| الإطلاق | `Queuety::workflow('name')->then(...)->dispatch()` | `Queuety::run_workflow('name', $payload)` |
| إعادة الاستخدام | إنشاء سلسلة الخطوات في كل مرة | التسجيل مرة واحدة والإطلاق مرات عديدة |
| الأنسب لـ | مهام سير العمل لمرة واحدة أو المُركّبة ديناميكيًا | العمليات القياسية القابلة للتكرار |