# Olekumasinad

Olekumasinad ja töövood lahendavad erinevaid probleeme.

Töövoog vastab küsimusele „milline töö järgmisena käivitatakse?”. Olekumasin vastab küsimusele „millises olekus see objekt on ja millised sündmused on sellest olekust alates lubatud?”. See erinevus on oluline siis, kui loodav objekt pole lihtsalt sammude jada, vaid pikaealine üksus, mis reageerib aja jooksul välisele sisendile, näiteks agendi seanss, vestluslõim, ülevaatuse elutsükkel, pilet või kinnitamisvoog.

## Kiire näide

```php
use Queuety\Enums\StateMachineStatus;
use Queuety\Queuety;

$machine_id = Queuety::machine( 'agent_session' )
    ->version( 'agent-session.v1' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'awaiting_review' )
    ->state( 'awaiting_review' )
    ->on( 'approve', 'completed', ReviewApprovedGuard::class )
    ->on( 'reject', 'awaiting_user' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Queuety::machine_event(
    $machine_id,
    'user_message',
    [ 'message' => 'Find competitors for this product' ]
);

Queuety::machine_event(
    $machine_id,
    'approve',
    [ 'approved' => true, 'reviewer' => 'editor@example.com' ]
);
```

See masin alustab olekus `awaiting_user`, liigub kasutaja sõnumi saabumisel olekusse `planning`, laseb järjekorda lisatud toimingul väljastada `planned` ning ootab seejärel olekus `awaiting_review`, kuni väline kinnitus seansi lõpetab. Oluline pole üksnes koodi süntaks. Oluline on see, et elutsükkel on selgesõnaline, kontrollitav ja sündmustepõhine.

## Kuidas masin töötab

Masinainstantsi käivitamisel salvestab Queuety praeguse oleku nime, avaliku olekuandmestiku, definitsiooni versiooni ja räsi, praeguse oleku jaoks lubatud sissetulevad sündmused ning püsiva sündmuste ajajoone.

Kui masin siseneb olekusse, millel on `action()`, lisab Queuety järjekorda olekusse sisenemise töö. See toiming võib lihtsalt avalikku olekut värskendada ja jätta masina järgmist sündmust ootama või väljastada `_event` ning soovi korral `_event_payload`, et käivitada kohe järgmine üleminek. Kui olekul pole toimingut ega lõppoleku staatust, jääb masin lihtsalt ootama väliseid sündmusi, mis saadetakse `Queuety::machine_event()` abil.

## Töövoogude ja olekumasinate valimine

Kasuta töövoogu, kui käivitus põhineb peamiselt sammudel: hangi andmed, töötle iga üksus, oota, koosta tulemus, lõpeta. See mudel sobib hästi siis, kui algus ja lõpp on selged ning peamine küsimus on, milline töö järgmisena käivitada.

Kasuta olekumasinat, kui lubatud käitumine sõltub elutsükli praegusest etapist. See sobib paremini siis, kui sündmused võivad saabuda eri järjekorras, objekt võib kaua olemas olla või vajad elutsükli selgesõnalist kontrollimist olekute `awaiting_user`, `planning`, `running_agents`, `awaiting_review` ja `completed` kaudu.

## Kuidas need kaks koos toimivad

Need kaks põhikomponenti toimivad kõige paremini koos, mitte teineteisega konkureerides. Olekutoiming võib käivitada töövoo, kui üleminek nõuab mahukamat täitmist, ning töövoog võib töö lõppedes masinale sündmuse saata. Nii juhib olekumasin elutsüklit, samal ajal kui töövood teevad mahuka või rangelt struktureeritud töö.

## Ehitaja ülesehitus

`StateMachineBuilder` jääb meelega väikeseks. `initial()` ja `state()` määravad elutsükli olekugraafi. `action()` seob järjekorras oleva töö ühe olekuga. `on()` määrab, millised sündmused võivad masina järgmisse olekusse viia. `on_queue()`, `with_priority()` ja `max_attempts()` määravad, kuidas olekutoiminguid täidetakse, samal ajal kui `version()` ja `idempotency_key()` lisavad püsivad käivituse metaandmed. `dispatch()` loob masina instantsi.

Olekutoimingud võivad pakkuda ka valikulist meetodit `config()`, kasutades samu ressursipoliitika võtmeid nagu töövoo sammud ja käsitlejad. Nii saab kuluka olekuülemineku paigutada jagatud samaaegsusrühma või lisada sellele suurema kulukaalu, kui toiming tarbib tavalisest sammust rohkem eelarvet.

Laiemat ressursimudelit kirjeldab [Ressursihaldus](https://queuety.inline0.dev/et/docs/features/resource-management).

## Lepingud

Olekusse sisenemise toimingud rakendavad liidest `Queuety\Contracts\StateAction`:

```php
namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}
```

`$payload` on toimingu definitsiooni struktureeritud andmestik; kui toiming määrati lihtsa klassinimena, on see tühi. Queuety loob toiminguid `new $class()` abil, seega peab toiminguklassi konstruktori saama käivitada nõutavate argumentideta.

Olekutoimingud võivad määratleda ka valikulise meetodi `config()` parameetritega `concurrency_group`, `concurrency_limit` ja `cost_units`, kui järjekorras olev sisenemistoiming peab osalema töötajate vastuvõtus, kaalutud järjekorra või teenusepakkuja eelarve haldamises ning muudes ressursipoliitikates.

Üleminekuvalvurid rakendavad liidest `Queuety\Contracts\StateGuard`:

```php
namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}
```

## Kontrollimise API-d

Kasuta töötavate masinate kontrollimiseks fassaadi:

```php
$status   = Queuety::machine_status( $machine_id );
$machines = Queuety::list_machines();
$events   = Queuety::machine_timeline( $machine_id );
$trace    = Queuety::machine_trace( $machine_id );
$state    = Queuety::machine_state_at( $machine_id, $event_id );
```

Olekumasinatel pole WP-CLI käske: `wp queuety workflow ...` hõlmab ainult töövooge. Kasuta neid PHP API-sid, näiteks `wp eval` kaudu, et masinaid käsurealt kontrollida.

Need API-d annavad teada praeguse oleku nime, elutsükli staatuse, avaliku oleku, saadaolevad sündmused, definitsiooni metaandmed, täieliku üleminekute ajajoone ning siluri kasutajaliideste jaoks normaliseeritud jäljepaketi. Masinate loendi ridadel on definitsiooni versioon, definitsiooni räsi ja idempotentsusvõti, et loendivaated saaksid kuvada lähte- ja käituskeskkonna versiooni ilma iga masinat eraldi laadimata. Jäljepakett sisaldab rühmitatud olekuid, toorsündmusi, seotud toimingutöid, logisid, artefaktiviiteid, tükiviiteid, käsitleja sisendit ja väljundit, olekut enne ja pärast, konteksti, ajastusi ning struktureeritud vigu.

## Agendiseansid

Olekumasinad on eriti kasulikud agendisüsteemides, mis toimivad pigem seansside kui konveieritena. Seanssi, mis liigub läbi olekute `awaiting_user`, `planning`, `running_agents`, `awaiting_review` ja `completed`, on tavaliselt lihtsam mõista selgesõnalise elutsüklina kui ühe väga pika töövoo definitsioonina, kus on palju ootamisi ja tagasihüppeid.

## Vt ka

- [Neuron Seansi olekumasin](https://queuety.inline0.dev/et/docs/examples/neuron-session-state-machine)
- [Neuron Mälu ja ülevaatuse olekumasin](https://queuety.inline0.dev/et/docs/examples/neuron-memory-review)
- [Agendi orkestreerimine](https://queuety.inline0.dev/et/docs/workflows/agent-orchestration)
- [Töövoo signaalid](https://queuety.inline0.dev/et/docs/workflows/signals)
- [Töövoo sõltuvused](https://queuety.inline0.dev/et/docs/workflows/dependencies)
- [Kordused](https://queuety.inline0.dev/et/docs/workflows/repeats)
- [Artefaktid](https://queuety.inline0.dev/et/docs/features/artifacts)
- [PHP API](https://queuety.inline0.dev/et/docs/api)