# Työnkulkujen riippuvuudet

Käytä työnkulkujen riippuvuusodotuksia, kun ylätason työnkulun tulisi jatkua vasta muiden työnkulkujen valmistuttua. Näin voit koordinoida työnkulkuja pakottamatta kaikkea yhteen suureen työnkulun määritelmään.

Nämä odotukset sopivat erityisen hyvin yhteen [Async Handoffs](https://queuety.inline0.dev/fi/docs/workflows/async-handoffs)-toiminnon kanssa, jossa yksi työnkulku käynnistää ensin itsenäiset alityönkulut ja odottaa niitä myöhemmin.

Katso kattavammat suunnittelija/suorittaja-esimerkit kohdasta [Agent Orchestration](https://queuety.inline0.dev/fi/docs/workflows/agent-orchestration).

Queuety tarjoaa kolme rakentajametodia:

- `wait_for_workflow()` yhdelle työnkululle
- `wait_for_workflows()` useille työnkuluille, joiden `all`-, `any`- tai `quorum`-semantiikkaa käytetään
- `wait_for_workflow_group()`, kun työnkulkujen tunnukset saadaan aiemmin käynnistetystä ryhmästä

## Odota yhtä työnkulkua

```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();
```

Kun `research_run` valmistuu, `editorial_run` jatkaa. Kun `result_key` on asetettu, valmistuneen riippuvuuden tila tallennetaan kyseisen avaimen alle:

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

Ilman `result_key`-arvoa riippuvuustyönkulun julkinen tila yhdistetään odottavan työnkulun ylimmän tason tilaan.

## Odota useita työnkulkuja

```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` jatkaa vasta, kun kaikki luetellut työnkulut ovat valmistuneet.
- `WaitMode::Any` jatkaa, kun ensimmäinen luetelluista työnkuluista valmistuu.
- `WaitMode::Quorum` jatkaa, kun vaadittu määrä työnkulkuja on valmistunut onnistuneesti.

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

Kun `result_key` on käytössä, usean työnkulun odotuksissa valmistuneiden riippuvuuksien tila tallennetaan työnkulun tunnuksen mukaan:

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

Ilman `result_key`-arvoa valmistuneiden riippuvuuksien tila yhdistetään odottavan työnkulun ylimmän tason tilaan riippuvuusjärjestyksessä.

## Riippuvuustunnusten ratkaiseminen työnkulun tilasta

Voit lykätä riippuvuusluettelon muodostamista suoritusaikaan lukemalla työnkulkujen tunnukset julkisesta tilasta:

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

Useita riippuvuuksia varten:

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

## Odota käynnistettyä työnkulkuryhmää

Jos aiempi `start_workflows()`- tai `start_agents()`-vaihe tallensi pysyvän ryhmäavaimen, voit odottaa suoraan kyseistä ryhmää sen sijaan, että välittäisit työnkulkujen tunnukset itse julkisen tilan kautta.

```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();
```

## Mitä odotuksen aikana tapahtuu

Kun työnkulku saavuttaa jonkin näistä vaiheista, sen tilaksi tulee `waiting_for_workflows`. Mikään työntekijä ei pysy siihen liitettynä odotuksen aikana.

```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']
```

Jos riippuvuus on jo valmistunut ennen odotusvaiheen saavuttamista, työnkulku jatkuu heti.

## Virhetilanteiden semantiikka

Työnkulun riippuvuusodotukset painottavat onnistumista:

- `wait_for_workflow()` ja `WaitMode::All` epäonnistuvat, jos jokin vaadittu riippuvuus epäonnistuu tai peruutetaan.
- `WaitMode::Any` epäonnistuu vain, kun kaikki riippuvuudet ovat päättyneet eikä yksikään valmistunut onnistuneesti.
- `WaitMode::Quorum` epäonnistuu, kun jäljellä olevat aktiiviset työnkulut eivät enää voi saavuttaa vaadittua päätösvaltaisuutta.

Näin työnkulkujen odotukset soveltuvat suunnittelija/suorittaja-järjestelmiin, joissa yksi työnkulku voi luoda kunkin työn ja toinen odottaa `all`-tuloksia tai ensimmäistä valmistuvaa onnistunutta haaraa.