# 순차 체인

가장 일반적인 워크플로 패턴은 단계의 선형 체인입니다. 각 단계는 이전 단계가 완료된 뒤 실행되며, 누적된 상태가 다음 단계로 전달됩니다.

## `->then()` 메서드

`->then()`을 사용해 워크플로에 순차 단계를 추가하세요:

```php
use Queuety\Queuety;

Queuety::workflow( 'onboarding' )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class )
    ->then( NotifyAdminHandler::class )
    ->dispatch( [ 'email' => 'user@example.com' ] );
```

단계는 추가된 순서대로 실행됩니다. 현재 단계가 성공적으로 완료되어야 워크플로가 다음 단계로 진행합니다.

## Step 인터페이스

워크플로 단계 핸들러는 `Queuety\Step` 인터페이스를 구현합니다:

```php
use Queuety\Step;

class CreateAccountHandler implements Step {
    public function handle( array $state ): array {
        $user_id = wp_create_user( $state['email'], wp_generate_password() );
        return [ 'user_id' => $user_id ];
    }

    public function config(): array {
        return [
            'max_attempts' => 3,
        ];
    }
}
```

`Handler` 인터페이스와 다른 주요 점:

| | `Handler` (작업) | `Step` (워크플로) |
|---|---|---|
| 메서드 시그니처 | `handle(array $payload): void` | `handle(array $state): array` |
| 입력 | 작업 페이로드 | 누적된 워크플로 상태 |
| 출력 | 없음(void) | 상태에 병합할 데이터 |

## 상태 흐름

각 단계는 누적된 전체 상태를 받고 새 키-값 쌍의 배열을 반환합니다. 반환된 데이터는 이후 단계에서 사용할 수 있도록 상태에 병합됩니다:

```php
class FetchUserHandler implements Step {
    public function handle( array $state ): array {
        // $state contains: ['user_id' => 42]
        $user = get_user_by( 'ID', $state['user_id'] );
        return [ 'user_name' => $user->display_name, 'user_email' => $user->user_email ];
    }

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

class GenerateReportHandler implements Step {
    public function handle( array $state ): array {
        // $state contains: ['user_id' => 42, 'user_name' => 'Alice', 'user_email' => 'alice@example.com']
        $report = build_report( $state['user_name'] );
        return [ 'report_url' => $report->url ];
    }

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

## 단계 구성

`config()` 메서드는 다음 키를 지원합니다:

| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| `max_attempts` | `int` | `3` | 이 단계의 최대 재시도 횟수 |
| `backoff` | `string` | `exponential` | 재시도를 위한 백오프 전략 |

## LLM 파이프라인 예시

일반적인 사용 사례는 LLM API 호출을 데이터 처리와 연결하는 것입니다:

```php
use Queuety\Step;

class BuildPromptHandler implements Step {
    public function handle( array $state ): array {
        $user = get_user_by( 'ID', $state['user_id'] );
        $posts = get_posts( [ 'author' => $user->ID, 'numberposts' => 10 ] );
        $context = implode( "\n", array_map( fn( $p ) => $p->post_content, $posts ) );

        return [
            'prompt' => "Summarize this author's recent work:\n\n{$context}",
        ];
    }

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

class CallOpenAIHandler implements Step {
    public function handle( array $state ): array {
        $response = wp_remote_post( 'https://api.openai.com/v1/chat/completions', [
            'timeout' => 120,
            'headers' => [
                'Authorization' => 'Bearer ' . OPENAI_API_KEY,
                'Content-Type'  => 'application/json',
            ],
            'body' => json_encode( [
                'model'    => 'gpt-4',
                'messages' => [ [ 'role' => 'user', 'content' => $state['prompt'] ] ],
            ] ),
        ] );

        $body = json_decode( wp_remote_retrieve_body( $response ), true );
        return [ 'summary' => $body['choices'][0]['message']['content'] ];
    }

    public function config(): array {
        return [ 'max_attempts' => 5 ];
    }
}

class SaveSummaryHandler implements Step {
    public function handle( array $state ): array {
        $post_id = wp_insert_post( [
            'post_title'   => "Summary for user #{$state['user_id']}",
            'post_content' => $state['summary'],
            'post_status'  => 'publish',
        ] );
        return [ 'summary_post_id' => $post_id ];
    }

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

파이프라인을 실행합니다:

```php
Queuety::workflow( 'summarize_author' )
    ->then( BuildPromptHandler::class )
    ->then( CallOpenAIHandler::class )
    ->then( SaveSummaryHandler::class )
    ->on_queue( 'llm' )
    ->max_attempts( 5 )
    ->dispatch( [ 'user_id' => 42 ] );
```

OpenAI 호출이 시간 초과되면 작업자는 해당 단계만 재시도합니다. 0단계에서 만든 프롬프트는 이미 워크플로 상태에 안전하게 저장되어 있습니다.