# Töövoogude sõltuvused

Kasuta töövoogude sõltuvuste ootamist, kui üks tipptaseme töövoog peaks jätkuma alles pärast teiste töövoogude lõpulejõudmist. Nii saad töövooge koordineerida, surumata kogu loogikat ühte hiiglaslikku töövoomääratlusse.

Need ootamised sobivad eriti hästi kokku [asünkroonsete üleandmistega](https://queuety.inline0.dev/et/docs/workflows/async-handoffs), kus üks töövoog käivitab esmalt sõltumatud alam töövood ja ootab neid hiljem.

Täielikumaid planeerija ja täitja näiteid leiad jaotisest [Agentide orkestreerimine](https://queuety.inline0.dev/et/docs/workflows/agent-orchestration).

Queuety pakub kolme koostajameetodit:

- `wait_for_workflow()` ühe töövoo jaoks
- `wait_for_workflows()` mitme töövoo jaoks semantikaga `all`, `any` või `quorum`
- `wait_for_workflow_group()`, kui töövoogude ID-d pärinevad varem käivitatud rühmast

## Oota üht töövoogu

```php
$research_id = Queuety::workflow( 'research_run' )
    ->then( PlanResearchStep::class )
    ->for_each( 'tasks', ExecuteResearchTask::class, 'results' )
    ->dispatch( [ 'brief_id' => 42 ] );

$editorial_id = Queuety::workflow( 'editorial_run' )
    ->wait_for_workflow( $research_id, 'research' )
    ->then( DraftBriefStep::class )
    ->dispatch();
```

Kui `research_run` lõpetab, jätkab `editorial_run` tööd. Kui määratud on `result_key`, talletatakse lõpetatud sõltuvuse olek selle võtme alla:

```php
$state['research']; // public state from the completed research workflow
```

Ilma `result_key`-ta liidetakse sõltuvustöövoo avalik olek ootava töövoo tipptaseme olekusse.

## Oota mitut töövoogu

```php
use Queuety\Enums\WaitMode;

Queuety::workflow( 'synthesis_run' )
    ->wait_for_workflows(
        [ $research_id, $editorial_id, $legal_id ],
        WaitMode::All,
        'dependencies'
    )
    ->then( PublishPacketStep::class )
    ->dispatch();
```

- `WaitMode::All` jätkab tööd alles siis, kui kõik loetletud töövood on lõpule jõudnud.
- `WaitMode::Any` jätkab tööd esimese loetletud töövoo lõpule jõudmisel.
- `WaitMode::Quorum` jätkab tööd, kui nõutud arv töövooge on edukalt lõpule jõudnud.

```php
Queuety::workflow( 'synthesis_run' )
    ->wait_for_workflows(
        [ $research_id, $editorial_id, $legal_id ],
        WaitMode::Quorum,
        'dependencies',
        quorum: 2,
    )
    ->then( PublishPacketStep::class )
    ->dispatch();
```

Kui määratud on `result_key`, salvestavad mitme töövoo ootamised lõpetatud sõltuvuste oleku töövoo ID järgi:

```php
[
    '42' => [ 'summary' => '...' ],
    '43' => [ 'summary' => '...' ],
]
```

Ilma `result_key`-ta liidetakse lõpetatud sõltuvuste olek sõltuvuste järjekorras ootava töövoo tipptaseme olekusse.

## Sõltuvuste ID-de määramine töövoo oleku põhjal

Sõltuvuste loendi saab edasi lükata käitusajani, lugedes töövoo avalikust olekust töövoogude ID-d:

```php
Queuety::workflow( 'agent_follow_up' )
    ->wait_for_workflow( 'parent_workflow_id', 'parent' )
    ->then( FinalizeAgentRunStep::class )
    ->dispatch( [ 'parent_workflow_id' => $workflow_id ] );
```

Mitme sõltuvuse korral:

```php
Queuety::workflow( 'aggregator' )
    ->wait_for_workflows( 'dependency_ids', WaitMode::Any, 'winner' )
    ->dispatch( [ 'dependency_ids' => [ 12, 18, 22 ] ] );
```

## Oota käivitatud töövoogude rühma

Kui eelmine samm `start_workflows()` või `start_agents()` salvestas püsiva rühma võtme, saad ise töövoogude ID-sid avaliku oleku kaudu edastamata otse selle rühma ootama jääda.

```php
Queuety::workflow( 'brief_research' )
    ->then( PlanTopicsStep::class )
    ->start_agents( 'agent_tasks', $agent_run, group_key: 'researchers' )
    ->wait_for_agent_group( 'researchers', WaitMode::Quorum, 2, 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch();
```

## Mis ootamise ajal juhtub

Kui töövoog jõuab ühe sellise sammuni, muutub selle olekuks `waiting_for_workflows`. Ootamise ajal ei jää ükski töötaja sellega seotuks.

```php
$state = Queuety::workflow_status( $workflow_id );
echo $state->status->value; // 'waiting_for_workflows'
echo $state->wait_type;     // 'workflow'
print_r( $state->waiting_for ); // ['42', '43']
```

Kui sõltuvus on enne ootamissammuni jõudmist juba lõpule jõudnud, jätkub töövoog kohe.

## Tõrgete käsitlemine

Töövoogude sõltuvuste ootamine eeldab edukat lõpulejõudmist:

- `wait_for_workflow()` ja `WaitMode::All` nurjuvad, kui mõni nõutud sõltuvus nurjub või tühistatakse.
- `WaitMode::Any` nurjub ainult siis, kui kõik sõltuvused on jõudnud lõppolekusse ja ükski neist pole edukalt lõpule jõudnud.
- `WaitMode::Quorum` nurjub, kui allesjäänud aktiivsed töövood ei suuda enam nõutud kvoorumit täita.

Seetõttu sobivad töövoogude ootamised planeerija ja täitja süsteemidesse, kus üks töövoog saab tööd koordineerida ja teine oodata `all` tulemusi või esimest edukat haru, mis lõpule jõuab.