# Työnkulun peruuttaminen

Työnkulkuja voi peruuttaa ohjelmallisesti tai CLI-toiminnolla. Kun työnkulku peruutetaan, Queuety asettaa sen tilaksi `cancelled`, hautaa odottavat tai käsiteltävät työt ja suorittaa halutessasi siivouskäsittelijän.

## Siivouskäsittelijän rekisteröinti

Rekisteröi työnkulun muodostajaan `on_cancel()`-toiminnolla luokka, joka suoritetaan työnkulun peruuntuessa. Käsittelijäluokan on toteutettava `handle( array $state ): void`-menetelmä.

```php
use Queuety\Queuety;

Queuety::workflow( 'import_data' )
    ->then( FetchDataHandler::class )
    ->then( TransformDataHandler::class )
    ->then( LoadDataHandler::class )
    ->on_cancel( ImportCleanupHandler::class )
    ->dispatch( [ 'source_url' => $url ] );
```

Siivouskäsittelijä saa julkisen työnkulun tilan (kaikki avaimet, jotka eivät ala merkillä `_`):

```php
class ImportCleanupHandler {

    public function handle( array $state ): void {
        // Clean up any partial imports.
        if ( isset( $state['temp_table'] ) ) {
            global $wpdb;
            $wpdb->query( "DROP TABLE IF EXISTS {$state['temp_table']}" );
        }

        // Notify the user.
        wp_mail(
            $state['notify_email'] ?? '',
            'Import cancelled',
            'Your data import was cancelled.'
        );
    }
}
```

## Peruuttaminen PHP-toiminnolla

Kutsu `Queuety::cancel_workflow()`-toimintoa työnkulun tunnisteella:

```php
Queuety::cancel_workflow( $workflow_id );
```

Tämä menetelmä:

1. Lukitsee työnkulun rivin
2. Asettaa työnkulun tilaksi `cancelled`
3. Hautaa kaikki työnkulun odottavat ja käsiteltävät työt viestillä "Workflow cancelled"
4. Kirjaa `workflow_cancelled`-tapahtuman ja vahvistaa tapahtuman
5. Suorittaa valmiiden vaiheiden korvaustoiminnot käänteisessä järjestyksessä (jos niitä on rekisteröity toiminnolla `compensate_with()`)
6. Suorittaa `on_cancel`-siivouskäsittelijän (jos se on rekisteröity)

`RuntimeException` heitetään, jos työnkulku on jo tilassa `completed` tai `cancelled`.

## Peruuttaminen CLI-toiminnolla

```bash
wp queuety workflow cancel <id>
```

| Valitsin | Kuvaus |
|---|---|
| `<id>` | Peruutettavan työnkulun tunniste (pakollinen) |

```bash
wp queuety workflow cancel 42
```

## Mitä peruutettaessa tapahtuu

Kun työnkulku peruutetaan:

- **Tila** muuttuu tilaksi `cancelled`
- **Vaiheiden korvaustoiminnot** suoritetaan valmistumisjärjestykseen nähden käänteisessä järjestyksessä, jos liitit ne toiminnolla `compensate_with()`
- **Siivouskäsittelijä** suoritetaan, kun työnkulun rivi on merkitty tilaan `cancelled`
- **Odottavat työt** työnkulussa haudataan välittömästi
- **Käsiteltävät työt** työnkulussa haudataan; kun käynnissä oleva käsittelijä valmistuu, sen tuloste hylätään eikä työnkulku etene
- **Valmiit työt** aiemmista vaiheista jätetään ennalleen
- **Lokimerkintä**, jonka tapahtuma on `workflow_cancelled`, tallennetaan

## Peruutettu ja epäonnistunut

| Ominaisuus | Epäonnistunut | Peruutettu |
|---|---|---|
| Käynnistin | Vaihe käyttää uudelleenyritysyrityksensä loppuun | `cancel_workflow()`-toiminnon nimenomainen kutsu |
| Tila | `failed` | `cancelled` |
| Voiko yrittää uudelleen | Kyllä, toiminnolla `retry_workflow()`, ellei työnkululle ole jo tehty korvaustoimintoja | Ei |
| Siivouskäsittelijä | Ei kutsuta | Kutsutaan, jos rekisteröity toiminnolla `on_cancel()` |
| Lokitapahtuma | `workflow_failed` | `workflow_cancelled` |

## Esimerkki: peruuttaminen vahvistuksen kanssa

Yleinen käytäntö on tarkistaa työnkulun tila ennen sen peruuttamista:

```php
$status = Queuety::workflow_status( $workflow_id );

if ( null === $status ) {
    throw new \RuntimeException( 'Workflow not found.' );
}

if ( 'running' === $status->status->value || 'paused' === $status->status->value ) {
    Queuety::cancel_workflow( $workflow_id );
}
```