# Dépendances entre flux de travail

Utilisez les attentes de dépendance entre flux lorsqu’un flux de premier niveau ne doit continuer qu’après la fin d’autres flux. Vous pouvez ainsi coordonner plusieurs flux sans tout regrouper dans une seule définition gigantesque.

Ces attentes se combinent particulièrement bien avec les [transferts asynchrones](https://queuety.inline0.dev/fr/docs/workflows/async-handoffs) : un flux démarre d’abord des flux enfants indépendants, puis les attend plus tard.

Pour des exemples plus complets de planificateur et d’exécuteur, consultez [Orchestration d’agents](https://queuety.inline0.dev/fr/docs/workflows/agent-orchestration).

Queuety fournit trois méthodes de générateur :

- `wait_for_workflow()` pour un flux de travail
- `wait_for_workflows()` pour plusieurs flux avec une sémantique `all`, `any` ou `quorum`
- `wait_for_workflow_group()` lorsque les identifiants de flux proviennent d’un groupe démarré précédemment

## Attendre un flux de travail

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

Lorsque `research_run` se termine, `editorial_run` reprend. Si `result_key` est défini, l’état de la dépendance terminée est enregistré sous cette clé :

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

Sans `result_key`, l’état public du flux de dépendance est fusionné dans l’état de premier niveau du flux en attente.

## Attendre plusieurs flux de travail

```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` reprend uniquement lorsque tous les flux répertoriés sont terminés.
- `WaitMode::Any` reprend dès que le premier flux répertorié se termine.
- `WaitMode::Quorum` reprend dès qu’un nombre requis de flux est terminé avec succès.

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

Avec `result_key`, les attentes portant sur plusieurs flux enregistrent l’état des dépendances terminées sous forme de paires identifiant de flux et état :

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

Sans `result_key`, l’état des dépendances terminées est fusionné dans l’état de premier niveau du flux en attente, selon l’ordre des dépendances.

## Résoudre les identifiants des dépendances à partir de l’état du flux

Vous pouvez reporter la liste des dépendances jusqu’à l’exécution en lisant les identifiants des flux dans l’état public :

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

Pour plusieurs dépendances :

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

## Attendre un groupe de flux déjà démarré

Si une étape `start_workflows()` ou `start_agents()` précédente a enregistré une clé de groupe durable, vous pouvez attendre directement ce groupe au lieu de faire transiter vous-même les identifiants des flux dans l’état public.

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

## Fonctionnement de l’attente

Lorsqu’un flux de travail atteint l’une de ces étapes, il passe au statut `waiting_for_workflows`. Aucun worker ne lui reste attaché pendant l’attente.

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

Si une dépendance est déjà terminée lorsque l’étape d’attente est atteinte, le flux continue immédiatement.

## Sémantique des échecs

Les attentes de dépendance entre flux de travail privilégient la réussite :

- `wait_for_workflow()` et `WaitMode::All` échouent si une dépendance requise échoue ou est annulée.
- `WaitMode::Any` échoue uniquement lorsque toutes les dépendances ont atteint un état terminal et qu’aucune n’a réussi.
- `WaitMode::Quorum` échoue lorsque les flux encore actifs ne peuvent plus satisfaire le quorum requis.

Les attentes entre flux sont donc utiles dans les systèmes de planificateur et d’exécuteur : un flux peut répartir le travail et un autre attendre les résultats de `all` ou la première branche terminée avec succès.