# Úvod

Queuety je doplnok WordPress, ktorý poskytuje rýchly front úloh, odolný nástroj na riadenie pracovných postupov a runtime prostredie odolného stavového automatu. Pracovníci si nárokujú úlohy priamo z MySQL a spracúvajú ich v dlho bežiacom procese WP-CLI. Runtime prostredie PHP, ktoré načítava WordPress a WP-CLI, potrebuje buď `mysqli`, alebo `pdo_mysql`.

## Prečo Queuety?

WordPress nemá skutočný systém úloh na pozadí. `wp_cron` sa spúšťa iba pri návštevách stránok. Predvolený spúšťač Action Scheduler využíva WP-Cron a požiadavky HTTP na lokálnu adresu; každú požiadavku spracúva v dávkach najviac 30 sekúnd. Volanie API od LLM, ktoré trvá 60 sekúnd, ukončí 30-sekundový časový limit PHP. Nemožno spúšťať viackrokové procesy, ktoré prežijú zlyhania a pokračujú od miesta, kde sa prerušili.

Queuety to rieši pomocou troch základných prvkov:

1. **Úlohy** na prácu na pozadí bez čakania na výsledok
2. **Workflowy** na trvácne viackrokové procesy s uloženým stavom
3. **Stavové automaty** na dlhodobý životný cyklus riadený udalosťami

## Rýchly príklad

Odošlite úlohu pomocou modernej API:

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

Alebo použite klasický prístup s názvom obslužnej rutiny:

```php
use Queuety\Queuety;

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

Spustite trvácny workflow:

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

Modelujte dlhotrvajúcu reláciu pomocou stavového automatu:

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

Spustite pracovníka:

```bash
wp queuety work
```

Ak vytvárate systém v štýle agenta, začnite témou [Orchestrácia agentov](https://queuety.inline0.dev/sk/docs/workflows/agent-orchestration). Ukazuje, ako spolu súvisia toky plánovania a vykonávania, kontrolné kroky s ľudským dohľadom a čakanie medzi workflowmi.

Ak je systém riadený udalosťami a má dlhú životnosť, okrem workflowov začnite témou [Stavové automaty](https://queuety.inline0.dev/sk/docs/state-machines).

Ak hľadáte príklady integrácie od začiatku do konca, pozrite si [Príklady](https://queuety.inline0.dev/sk/docs/examples), ktoré teraz obsahujú vzory založené na Neuron na prepínanie poskytovateľov, streamovanie, opakovanie kontroly s podporou pamäte a závislé workflowy.

Ak chcete spúšťať workflowy na základe doménových udalostí WordPress, ako je `save_post`, pozrite si [Spúšťače akcií](https://queuety.inline0.dev/sk/docs/features/action-triggers).

Ak chcete používať prostredie s databázou mimo WordPress, pozrite si [Samostatné použitie](https://queuety.inline0.dev/sk/docs/features/standalone-use).

## Kľúčové odlišnosti

- **Rýchle vykonávanie.** Pracovníci pristupujú priamo k frontu MySQL a vyhýbajú sa vzoru cron pri každej požiadavke, ktorý spomaľuje prácu na pozadí v WordPress.
- **Trvácne workflowy.** Viackrokové procesy s uloženým stavom, ktoré odolávajú časovým limitom PHP, zlyhaniam a opakovaniam. Hranica každého kroku tvorí atómovú transakciu MySQL.
- **Explicitné stavové automaty.** Modelujte chatovacie relácie, schvaľovania a ďalšie dlhotrvajúce životné cykly pomocou pomenovaných stavov, strážených prechodov, úloh zaradených do frontu pri vstupe do stavu a trvácnych časových osí udalostí.
- **Moderné API na odosielanie úloh API.** Samostatné triedy úloh s traitom `Dispatchable`, typovanými vlastnosťami konštruktora ako údajmi úlohy a deklaráciami `$tries`/`$timeout`/`$backoff` v triede. Trieda `readonly` nemôže týmto vlastnostiam nastaviť predvolené hodnoty, preto ich deklarujte v bežnej triede s vlastnosťami konštruktora propagovanými ako readonly.
- **Postupnosť middleware.** Middleware v štýle cibule na obmedzovanie frekvencie, tlmenie výnimiek, jedinečné úlohy a vlastnú logiku. Deklaruje sa pre každú úlohu pomocou metódy `middleware()`.
- **Streamované kroky.** Rozhranie `StreamingStep` poskytuje časti, ktoré sa okamžite ukladajú do databázy. Pri opakovanom pokuse sa poskytnú predtým uložené časti, takže streamovanie môže pokračovať od miesta prerušenia. Ideálne riešenie pre odpovede LLM a veľké súbory na stiahnutie.
- **Prispôsobiteľná vrstva cache.** `CacheFactory` automaticky zistí APCu alebo použije záložnú vyrovnávaciu pamäť v pamäti. Vlastné úložiská implementujú `Contracts\Cache`. Používa sa interne pri vyhľadávaní obmedzovačov frekvencie a stavu frontov.
- **Dávkovanie a reťazenie.** Odosielajte skupiny úloh s callbackmi `then`/`catch`/`finally` a sledovaním priebehu alebo reťazte úlohy postupne tak, že každá závisí od dokončenia predchádzajúcej.
- **Trvácne oneskorenia a čakanie.** `delay()` pridáva oneskorenia bezpečné pri reštarte procesu. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` a `wait_for_workflow()` umožňujú workflowom čakať na externé udalosti alebo iné workflowy bez toho, aby proces PHP musel zostať spustený.
- **Dynamický cyklus for-each.** `for_each()` rozširuje vetvy práce zistené za behu na základe stavu workflowu a podporuje režimy dokončenia: všetky úspešné, prvý úspešný a kvórum.
- **Asynchrónne odovzdávanie medzi workflowmi.** `start_workflows()` mení položky zistené za behu na nezávislé workflowy najvyššej úrovne, na ktoré možno čakať neskôr.
- **Spúšťače akcií WordPress.** `on_action()` mapuje hooky akcií jadra alebo pluginov na spustenia trvácnych workflowov s podmienkami a idempotenciou.
- **Trvácne artefakty.** Ukladajte pomenované výstupy workflowov mimo hlavného úložiska stavu a zahrňte ich do prehľadu stavu, kontroly CLI, exportu a prehrávania.
- **Ochranné prvky workflowov.** `version()`, deterministický hash definície, idempotentné kľúče odoslania a rozpočty workflowov uľahčujú kontrolu behov v štýle agentov a pomáhajú predísť ich duplikovaniu či nekontrolovanému predlžovaniu.
- **Správa zdrojov.** Skupiny súbežnosti, nákladové jednotky, rozpočty workflowov a prijímanie úloh pracovníkmi pomáhajú udržať náročnú prácu v štýle agentov v stanovených medziach.
- **Kompenzácia krokov.** `compensate_with()` a `compensate_on_failure()` poskytujú hooky na vrátenie dokončených krokov späť pri zrušení alebo zlyhaní workflowov.
- **Signály aktivity.** Dlho bežiace kroky odosielajú signály aktivity, aby systém obnovy zastaraných úloh neprevzal aktívnu prácu.
- **Sledovanie workflowov.** Každý prechod kroku sa zaznamenáva spolu so vstupom, výstupom, stavom pred a po zmene, kontextom, artefaktmi, časťami, chybami a ladením s prechodom v čase pomocou `workflow_state_at()`.
- **Paralelné kroky.** Spúšťajte kroky súbežne a pred pokračovaním čakajte na dokončenie všetkých.
- **Podmienené vetvenie.** Pomocou `_next_step` preskočte na pomenované kroky podľa predchádzajúceho stavu.
- **Spúšťanie workflowov.** Spúšťajte podriadené workflowy, ktoré vracajú výsledky nadradenému workflowu.
- **Fronty s prioritou.** Štyri úrovne (Low, Normal, High, Urgent) prostredníctvom typovo bezpečných enumov PHP.
- **Pracovníci pre viacero frontov.** Spracúvajte viacero frontov s prísnym poradím priorít v jednom pracovníkovi.
- **Obmedzovanie frekvencie.** Limity vykonávania pre jednotlivé obslužné rutiny s posuvným časovým oknom.
- **Opakované úlohy.** Plánovanie na základe intervalu a cron s konfigurovateľnými pravidlami prekrývania (Povoliť, Preskočiť, Uložiť do frontu).
- **Zrušenie workflowov.** Zrušte spustené workflowy a aktivujte zaregistrované obslužné rutiny na vyčistenie.
- **Prečisťovanie stavu.** Automaticky odstraňujte staré výstupy krokov, aby sa dal spravovať rozsiahly stav workflowov.
- **Súbežnosť pracovníkov.** `--workers=N` vytvára viacero procesov a po zlyhaní ich automaticky reštartuje.
- **Úplný prehľad.** Zaznamenávanie do databázy, metriky pre jednotlivé obslužné rutiny a webhooky udalostí.
- **Pomôcky na testovanie.** `QueueFake` zaznamenáva odoslané úlohy a dávky, aby sa dali overovať tvrdenia v jednotkových testoch.
- **Atribúty PHP.** `#[QueuetyHandler('name')]` na registráciu obslužných rutín bez konfigurácie.

## Ako to funguje

Pracovníci bežia v dlhodobo spustenom procese WP-CLI a preberajú úlohy priamo z MySQL. Riadky frontu, stav pracovného postupu, záznamy, dávky, signály aj časti streamu sú uložené v MySQL, takže reštart pracovníkov nespôsobí stratu stavu orchestrácie.

Pracovné postupy rozdeľujú dlhotrvajúcu prácu na kroky. Každý krok uloží svoj výstup do zdieľaného objektu stavu v databáze. Ak PHP počas kroku zlyhá, pracovník tento krok zopakuje a zachová celý predchádzajúci stav. Hranicu kroku tvorí jediná transakcia MySQL: aktualizácia stavu, dokončenie úlohy aj zaradenie ďalšieho kroku do frontu prebehnú atómovo.

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

## Požiadavky

- PHP 8.2 alebo novšia
- WordPress 6.4 alebo novšia
- MySQL 8.0+ alebo MariaDB 10.6+, pretože pracovníci preberajú úlohy pomocou `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` alebo `pdo_mysql` v prostredí PHP, ktoré načítava WordPress a WP-CLI
- WP-CLI na spúšťanie vyhradených pracovníkov s `wp queuety work`
- Rozšírenia `pcntl` a `posix` PHP pre skupiny pracovníkov (`--workers`, `--min-workers`, `--max-workers`)

Inštaláciu nájdete v časti [Začíname](https://queuety.inline0.dev/sk/docs/getting-started).