# Bevezetés

A Queuety egy WordPress bővítmény, amely gyors feladatsort, tartós munkafolyamat-motort és tartós állapotgép-futtatókörnyezetet biztosít. A workerek közvetlenül a MySQL rendszerből veszik át a feladatokat, és egy hosszú ideig futó WP-CLI folyamatban dolgozzák fel őket. A PHP futtatókörnyezetnek, amely betölti a WordPress és WP-CLI elemet, vagy a `mysqli`, vagy a `pdo_mysql` elemre van szüksége.

## Miért a Queuety?

A WordPress nem rendelkezik valódi háttérfeladat-rendszerrel. A `wp_cron` csak oldalmegtekintéskor fut le. Az Action Scheduler alapértelmezett futtatója a WP-Cron rendszerre és a loopback HTTP kérésekre támaszkodik; ezek legfeljebb 30 másodpercig dolgoznak fel kötegeket. Egy 60 másodpercig tartó LLM API hívást a PHP 30 másodperces időkorlátja megszakít. Nincs mód olyan többlépéses folyamatok futtatására, amelyek összeomlás esetén is megmaradnak, és ott folytatódnak, ahol abbamaradtak.

A Queuety három alapelemmel oldja meg ezt:

1. **Feladatok** a háttérben, aszinkron végrehajtandó munkához
2. **Munkafolyamatok** tartós állapotú, többlépéses folyamatokhoz
3. **Állapotgépek** a hosszú életű, eseményvezérelt életciklus-állapotokhoz

## Gyors példa

Feladat indítása a modern API használatával:

```php
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );
```

Vagy a klasszikus, kezelőnév-alapú megközelítést is használhatja:

```php
use Queuety\Queuety;

Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );
```

Tartós munkafolyamat futtatása:

```php
Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );
```

Hosszú életű munkamenet modellezése állapotgéppel:

```php
use Queuety\Enums\StateMachineStatus;

Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );
```

Worker indítása:

```bash
wp queuety work
```

Ha ügynökalapú rendszert épít, kezdje az [Ügynökvezénylés](https://queuety.inline0.dev/hu/docs/workflows/agent-orchestration) oldallal. Bemutatja, hogyan kapcsolódnak össze a tervező/végrehajtó folyamatok, az emberi felülvizsgálati ellenőrzőpontok és a munkafolyamatok közötti várakozások.

Ha a rendszer eseményvezérelt és hosszú életű, a munkafolyamatok mellett kezdje az [Állapotgépek](https://queuety.inline0.dev/hu/docs/state-machines) oldallal.

Ha teljes körű integrációs példákat keres, lásd a [Példák](https://queuety.inline0.dev/hu/docs/examples) oldalt, amely most a Neuron alapú mintákat is tartalmazza a szolgáltatóváltáshoz, a streameléshez, a memóriával támogatott felülvizsgálati ismétlésekhez és a függő munkafolyamatokhoz.

Ha azt szeretné, hogy a munkafolyamatok WordPress tartományi eseményekből, például a `save_post` eseményből induljanak, lásd a [Műveletindítók](https://queuety.inline0.dev/hu/docs/features/action-triggers) oldalt.

Ha az adatbázis-alapú futtatókörnyezetet a WordPress rendszeren kívül szeretné használni, lásd az [Önálló használat](https://queuety.inline0.dev/hu/docs/features/standalone-use) oldalt.

## Fő megkülönböztető jellemzők

- **Gyors végrehajtás.** A workerek közvetlenül férnek hozzá a MySQL sorhoz, és elkerülik a kérésenkénti cron mintát, amely lelassítja a háttérfeladatokat a WordPress környezetben.
- **Tartós munkafolyamatok.** Többlépéses folyamatok megőrzött állapottal, amelyek túlélik a PHP időtúllépéseit, összeomlásait és újrapróbálkozásait. Minden lépéshatár atomi MySQL tranzakció.
- **Kifejezett állapotgépek.** Csevegési munkameneteket, jóváhagyásokat és más hosszú élettartamú életciklusokat modellezhet névvel ellátott állapotokkal, feltételhez kötött átmenetekkel, sorba állított állapotbelépési műveletekkel és tartós esemény-idővonalakkal.
- **Modern dispatch API.** Önálló jobosztályok a `Dispatchable` traittel, payloadként szolgáló, típusos konstruktor-tulajdonságokkal, valamint az osztályon deklarált `$tries`/`$timeout`/`$backoff` elemekkel. Egy `readonly` osztály nem adhat alapértéket ezeknek a tulajdonságoknak, ezért deklarálja őket readonly, promoted konstruktor-tulajdonságokkal rendelkező hagyományos osztályban.
- **Middleware-folyamat.** Hagymahéj-szerű middleware sebességkorlátozáshoz, kivétel-fojtáshoz, egyedi jobokhoz és egyéni logikához. Jobonként, egy `middleware()` metódussal deklarálható.
- **Folyamatos lépések.** A `StreamingStep` interfész olyan adatdarabokat ad vissza, amelyek azonnal mentésre kerülnek az adatbázisba. Újrapróbálkozáskor a korábban mentett darabok is rendelkezésre állnak, így a folyam ott folytatható, ahol abbamaradt. Ideális LLM-válaszokhoz és nagy letöltésekhez.
- **Bővíthető gyorsítótárréteg.** A `CacheFactory` automatikusan felismeri az APCu-t, ennek hiányában memóriabeli gyorsítótárra vált. Egyéni háttértárak a `Contracts\Cache` megvalósításával készíthetők. Belsőleg sebességkorlátozó-lekérdezésekhez és a sor állapotához használatos.
- **Kötegelt feldolgozás és láncolás.** Jobcsoportokat indíthat a `then`/`catch`/`finally` visszahívásokkal és folyamatkövetéssel, vagy egymás után láncolhatja a jobokat, amelyek mindegyike az előző befejezésétől függ.
- **Tartós késleltetések és várakozások.** A `delay()` folyamat-újraindítást túlélő késleltetéseket ad hozzá. A `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` és `wait_for_workflow()` lehetővé teszi, hogy a munkafolyamatok külső eseményekre vagy más munkafolyamatokra várjanak anélkül, hogy életben kellene tartaniuk a PHP-t.
- **Dinamikus for-each.** A `for_each()` a munkafolyamat állapota alapján bontja ki a futás közben felfedezett ágfeladatokat, és támogatja az összes sikeres, az első sikeres, valamint a kvórumos befejezési módot.
- **Aszinkron munkafolyamat-átadások.** A `start_workflows()` a futás közben felfedezett elemekből önálló, legfelső szintű munkafolyamatokat hoz létre, amelyekre később várni lehet.
- **WordPress műveleti triggerek.** A `on_action()` a core- vagy pluginműveleti hookokat tartós munkafolyamat-indításokhoz rendeli, feltételekkel és idempotenciával.
- **Tartós artefaktumok.** A megnevezett munkafolyamat-kimeneteket a fő állapotcsomagon kívül tárolhatja, és továbbviheti őket az állapot, a CLI vizsgálat, az exportálás és az újrajátszás során.
- **Munkafolyamat-védőkorlátok.** A `version()`, a determinisztikus definícióhash, az idempotens indítási kulcsok és a munkafolyamat-keretek megkönnyítik az ügynökszerű futások vizsgálatát, valamint megakadályozzák a duplikálást és az észrevétlenül elhúzódó futást.
- **Erőforrás-kezelés.** A párhuzamossági csoportok, a költségegységek, a munkafolyamat-keretek és a workerfelvétel segítenek meghatározott keretek között tartani a költséges, ügynökszerű munkát.
- **Lépés-visszavonás.** A `compensate_with()` és a `compensate_on_failure()` visszaállítási hookokat biztosít a befejezett lépésekhez, ha a munkafolyamatokat megszakítják vagy hibát észlelnek.
- **Életjelek.** A hosszan futó lépések életjeleket küldenek, hogy az elavult jobok helyreállítási rendszere ne vegye át az aktív munkát.
- **Munkafolyamat-követés.** Minden lépésátmenet rögzítésre kerül a bemenettel, kimenettel, a korábbi és az új állapottal, a kontextussal, az artefaktumokkal, az adatdarabokkal, a hibákkal, valamint a `workflow_state_at()` segítségével végzett időutazásos hibakereséssel együtt.
- **Párhuzamos lépések.** A lépések egyidejűleg futnak, és a továbblépés előtt mindegyik befejezését megvárják.
- **Feltételes elágazás.** A korábbi állapot alapján névvel ellátott lépésekre ugorhat a `_next_step` használatával.
- **Munkafolyamatok futtatása.** Gyermek-munkafolyamatokat indíthat, amelyek visszajuttatják az eredményeiket a szülőhöz.
- **Prioritási sorok.** Négy szint (Low, Normal, High, Urgent) típusbiztos PHP enumokon keresztül.
- **Többsoros workerek.** Egyetlen workerben több sort dolgozhat fel szigorú prioritási sorrendben.
- **Sebességkorlátozás.** Kezelőnkénti végrehajtási korlátok gördülő időablakkal.
- **Ismétlődő jobok.** Intervallumalapú és cron alapú ütemezés konfigurálható átfedési szabályokkal (Allow, Skip, Buffer).
- **Munkafolyamat megszakítása.** Futó munkafolyamatokat szakíthat meg, és elindíthatja a regisztrált takarító kezelőket.
- **Állapottisztítás.** Automatikusan eltávolítja a régi lépéskimeneteket, hogy kezelhető maradjon a nagy munkafolyamat-állapot.
- **Worker-párhuzamosság.** A `--workers=N` több folyamatot indít, és összeomlás esetén automatikusan újraindítja őket.
- **Teljes megfigyelhetőség.** Adatbázis-naplózás, kezelőnkénti metrikák és esemény-webhookok.
- **Tesztelési segédeszközök.** A `QueueFake` rögzíti az elindított jobokat és kötegeket az egységtesztekben végzett ellenőrzésekhez.
- **PHP attribútumok.** A `#[QueuetyHandler('name')]` használatával nincs szükség konfigurációra a kezelők regisztrálásához.

## Működés

A workerek egy hosszan futó WP-CLI folyamaton belül futnak, és közvetlenül a MySQL-ből veszik fel a jobokat. A sorok, a munkafolyamat-állapot, a naplók, a kötegek, a jelek és a folyamatos adatdarabok mind a MySQL-ben élnek, így a worker újraindítása nem veszíti el a vezénylési állapotot.

A munkafolyamatok lépésekre bontják a hosszan futó feladatokat. Minden lépés elmenti a kimenetét egy megosztott, adatbázisbeli állapotcsomagba. Ha a PHP egy lépés közben leáll, a worker az összes korábbi állapot megőrzésével újrapróbálja az adott lépést. A lépéshatár egyetlen MySQL tranzakció: az állapot frissítése, a job befejezése és a következő lépés sorba állítása mind atomikusan történik.

```
Workflow: generate_report (3 steps)

Step 0: fetch_data     -> state: {user_data: {...}}
Step 1: call_llm       -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."}
Step 2: format_output  -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"}

Workflow: completed
```

## Követelmények

- PHP 8.2 vagy újabb
- WordPress 6.4 vagy újabb
- MySQL 8.0+ vagy MariaDB 10.6+, mivel a workerek `SELECT ... FOR UPDATE SKIP LOCKED` használatával veszik fel a jobokat
- `mysqli` vagy `pdo_mysql` a PHP futtatókörnyezetben, amely betölti a WordPress-t és a WP-CLI-t
- WP-CLI dedikált workerek futtatásához `wp queuety work` használatával
- A `pcntl` és `posix` PHP bővítmények a workerpoolokhoz (`--workers`, `--min-workers`, `--max-workers`)

Telepítési útmutatóért tekintse meg az [Első lépések](https://queuety.inline0.dev/hu/docs/getting-started) részt.