# Állapotgépek

Az állapotgépek és a munkafolyamatok különböző problémákat oldanak meg.

A munkafolyamat arra ad választ, hogy „milyen munka fut le legközelebb?”. Az állapotgép arra, hogy „milyen állapotban van ez az elem, és milyen események érvényesek ebből az állapotból?”. Ez a különbség akkor számít, amikor nem csupán lépések sorozatát építi, hanem egy hosszú életű entitást, amely idővel külső bemenetekre reagál, például egy ügynökmunkamenetet, csevegési szálat, felülvizsgálati életciklust, jegyet vagy jóváhagyási folyamatot.

## Gyors példa

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

Ez a gép a(z) `awaiting_user` állapotban indul, felhasználói üzenet érkezésekor a(z) `planning` állapotba lép, a sorba állított művelet kibocsátja a(z) `planned` eseményt, majd a(z) `awaiting_review` állapotban vár, amíg egy külső jóváhagyás be nem fejezi a munkamenetet. A lényeg nem önmagában a kód szintaxisa, hanem az, hogy az életciklus kifejezett, megvizsgálható és eseményvezérelt.

## Hogyan működik egy állapotgép

Egy géppéldány elküldésekor a(z) Queuety elmenti az aktuális állapot nevét, a nyilvános állapot-adattartalmat, a definíció verzióját és hashét, az aktuális állapotból érvényes bejövő eseményeket, valamint az események tartós idővonalát.

Ha a belépett állapothoz tartozik `action()`, a(z) Queuety sorba állít egy állapotbelépési feladatot. Ez a művelet egyszerűen frissítheti a nyilvános állapotot, majd várhat a következő eseményre, vagy kibocsáthatja a(z) `_event` eseményt, és opcionálisan a(z) `_event_payload` értéket is, hogy azonnal elindítsa a következő átmenetet. Ha az állapothoz nem tartozik művelet és nincs végállapota, a gép egyszerűen a(z) `Queuety::machine_event()` segítségével küldött külső eseményekre vár.

## Munkafolyamatok és állapotgépek közötti választás

Akkor használjon munkafolyamatot, ha a futás alapvetően lépésekből áll. Adatok lekérése, minden egyes munka végrehajtása, várakozás, összeállítás, befejezés. Ez a modell akkor illik jól, ha egyértelmű a kezdés és a befejezés, és az a fő kérdés, hogy milyen munka hajtódjon végre legközelebb.

Akkor használjon állapotgépet, ha az érvényes viselkedés az aktuális életciklusfázistól függ. Ez jobban illik, ha az események eltérő sorrendben érkezhetnek, az entitás hosszú ideig élhet, vagy az életciklust olyan állapotokkal kell kifejezetten megvizsgálnia, mint a(z) `awaiting_user`, `planning`, `running_agents`, `awaiting_review` és `completed`.

## Hogyan egészíti ki egymást a két megoldás

A két alapvető építőelem akkor működik a legjobban, ha együtt használja őket, nem pedig egymás versenytársaként. Egy állapotművelet elindíthat egy munkafolyamatot, ha az átmenet nagyobb végrehajtási feladatot igényel, a munkafolyamat pedig eseményt küldhet vissza az állapotgépnek, amikor a munka befejeződött. A gyakorlatban így az állapotgép irányítja az életciklust, a munkafolyamatok pedig elvégzik a költséges vagy szigorúan strukturált végrehajtást.

## A builder felépítése

A(z) `StateMachineBuilder` szándékosan egyszerű. A(z) `initial()` és `state()` határozza meg az életciklus gráfját. A(z) `action()` egy állapothoz kapcsol sorba állított munkát. A(z) `on()` adja meg, mely események léptethetik át a gépet a következő állapotba. A(z) `on_queue()`, `with_priority()` és `max_attempts()` szabályozza az állapotműveletek végrehajtását, míg a(z) `version()` és `idempotency_key()` tartós küldési metaadatokat kapcsol hozzájuk. A(z) `dispatch()` létrehozza a géppéldányt.

Az állapotműveletek egy választható `config()` metódust is biztosíthatnak, ugyanazokkal az erőforrás-szabályzati kulcsokkal, amelyeket a munkafolyamat-lépések és -kezelők használnak. Így egy költséges állapotátmenet egy megosztott párhuzamossági csoportba helyezhető, vagy nagyobb költségsúly rendelhető hozzá, ha a művelet több keretet használ fel, mint egy szokásos lépés.

A tágabb erőforrásmodellt az [Erőforrás-kezelés](https://queuety.inline0.dev/hu/docs/features/resource-management) ismerteti.

## Szerződések

Az állapotba belépéskor futó műveletek megvalósítják a(z) `Queuety\Contracts\StateAction` interfészt:

```php
namespace Queuety\Contracts;

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

A(z) `$payload` a műveletdefiníció strukturált adattartalma; üres, ha a műveletet egyszerű osztálynévként adták meg. A(z) Queuety a(z) `new $class()` segítségével hoz létre műveleteket, ezért a műveleti osztály konstruktorának nem lehetnek kötelező argumentumai.

Az állapotműveletek egy választható `config()` metódust is definiálhatnak a(z) `concurrency_group`, `concurrency_limit` és `cost_units` értékekkel, ha a sorba állított belépési műveletnek részt kell vennie a feldolgozói felvételben, a súlyozott sorban vagy a szolgáltatói keretkorlátokban, illetve más erőforrás-szabályzatokban.

Az átmeneti őrfeltételek megvalósítják a(z) `Queuety\Contracts\StateGuard` interfészt:

```php
namespace Queuety\Contracts;

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

## Vizsgálati API-k

A futó gépek vizsgálatához használja a homlokzati osztályt:

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

Az állapotgépekhez nincsenek WP-CLI parancsok: a(z) `wp queuety workflow ...` csak a munkafolyamatokat fedi le. A gépek parancssori vizsgálatához használja ezeket a(z) PHP API-kat, például a(z) `wp eval` segítségével.

Ezek az API-k megjelenítik az aktuális állapot nevét, az életciklus állapotát, a nyilvános állapotot, az elérhető eseményeket, a definíció metaadatait, az átmenetek teljes idővonalát, valamint a hibakereső felületekhez készült normalizált nyomkövetési csomagot. A géplisták sorai tartalmazzák a definíció verzióját és hashét, valamint az idempotenciakulcsot, így a listanézetek az egyes gépek külön betöltése nélkül is megjeleníthetik a forrás- és futtatókörnyezeti verziót. A nyomkövetési csomag csoportosított állapotokat, nyers eseményeket, korrelált műveleti feladatokat, naplókat, műtermékhivatkozásokat, darabhivatkozásokat, kezelői bemenetet és kimenetet, előtte és utána állapotot, kontextust, időzítéseket és strukturált hibákat tartalmaz.

## Ügynökmunkamenetek

Az állapotgépek különösen hasznosak a folyamatoknál inkább munkamenetekre hasonlító ügynökrendszerekben. Egy olyan munkamenetet, amely a(z) `awaiting_user`, `planning`, `running_agents`, `awaiting_review` és `completed` állapotokon halad át, általában könnyebb kifejezett életciklusként átlátni, mint egyetlen, nagyon hosszú munkafolyamat-definícióként, sok várakozással és visszacsatolással.

## Lásd még

- [Neuron Munkamenet-állapotgép](https://queuety.inline0.dev/hu/docs/examples/neuron-session-state-machine)
- [Neuron Memória- és felülvizsgálati állapotgép](https://queuety.inline0.dev/hu/docs/examples/neuron-memory-review)
- [Ügynökök összehangolása](https://queuety.inline0.dev/hu/docs/workflows/agent-orchestration)
- [Munkafolyamat-jelzések](https://queuety.inline0.dev/hu/docs/workflows/signals)
- [Munkafolyamat-függőségek](https://queuety.inline0.dev/hu/docs/workflows/dependencies)
- [Ismétlések](https://queuety.inline0.dev/hu/docs/workflows/repeats)
- [Műtermékek](https://queuety.inline0.dev/hu/docs/features/artifacts)
- [PHP API](https://queuety.inline0.dev/hu/docs/api)