# Uvod

Queuety je vtičnik za WordPress, ki ponuja hitro čakalno vrsto opravil, mehanizem trajnih potekov dela in izvajalno okolje za trajne avtomate stanj. Delavci prevzemajo opravila neposredno iz MySQL in jih obdelujejo v dolgotrajnem procesu WP-CLI. Izvajalno okolje PHP, ki nalaga WordPress in WP-CLI, potrebuje bodisi `mysqli` bodisi `pdo_mysql`.

## Zakaj Queuety?

WordPress nima pravega sistema za opravila v ozadju. `wp_cron` se sproži samo ob obiskih strani. Privzeti izvajalnik Action Scheduler deluje prek WP-Cron in zahtev zanke povratne zanke HTTP, pri čemer vsako zahtevo obdeluje v paketih največ 30 sekund. Klic LLM API, ki traja 60 sekund, prekine 30-sekundna časovna omejitev za PHP. Ni načina za izvajanje večstopenjskih procesov, ki preživijo sesutja in nadaljujejo tam, kjer so se ustavili.

Queuety to rešuje s tremi osnovnimi gradniki:

1. **Opravila** za delo v ozadju, ki se sproži brez čakanja na rezultat
2. **Poteki dela** za trajne večstopenjske procese s shranjenim stanjem
3. **Avtomati stanj** za dolgotrajna stanja življenjskega cikla, ki jih vodijo dogodki

## Kratek primer

Pošljite opravilo v izvajanje z uporabo sodobnega 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!' );
```

Lahko uporabite tudi klasični pristop z imenom obravnavalnika:

```php
use Queuety\Queuety;

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

Zaženite trajni potek dela:

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

Modelirajte dolgotrajno sejo z avtomatom stanj:

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

Zaženite delavca:

```bash
wp queuety work
```

Če gradite sistem v slogu agenta, začnite z razdelkom [Orkestracija agentov](https://queuety.inline0.dev/sl/docs/workflows/agent-orchestration). Prikazuje povezovanje potekov načrtovalca in izvajalca, kontrolnih točk za človeški pregled ter čakanja med poteki dela.

Če je sistem dolgotrajen in ga vodijo dogodki, poleg potekov dela začnite z razdelkom [Avtomati stanj](https://queuety.inline0.dev/sl/docs/state-machines).

Če želite primere integracije od začetka do konca, glejte [Primeri](https://queuety.inline0.dev/sl/docs/examples), ki zdaj vključujejo vzorce na osnovi Neuron za preklapljanje ponudnikov, pretakanje, ponavljanje pregledov s podporo pomnilnika in odvisne poteke dela.

Če želite poteke dela zagnati na podlagi domenskih dogodkov WordPress, kot je `save_post`, glejte razdelek [Sprožilci dejanj](https://queuety.inline0.dev/sl/docs/features/action-triggers).

Če želite izvajalno okolje s podporo zbirke podatkov uporabljati zunaj WordPress, glejte razdelek [Samostojna uporaba](https://queuety.inline0.dev/sl/docs/features/standalone-use).

## Ključne prednosti

- **Hitro izvajanje.** Delavci neposredno dostopajo do čakalne vrste MySQL in se izognejo vzorcu cron za vsako zahtevo, ki upočasnjuje delo v ozadju v WordPress.
- **Trajni poteki dela.** Večstopenjski procesi s shranjenim stanjem, ki preživijo časovne omejitve PHP, sesutja in ponovne poskuse. Meja vsakega koraka je atomska transakcija MySQL.
- **Izrecni avtomati stanj.** Modelirajte klepetalne seje, odobritve in druge dolgotrajne življenjske cikle z imenovanimi stanji, varovanimi prehodi, načrtovanimi dejanji ob vstopu v stanje in trajnimi časovnicami dogodkov.
- **Sodobno pošiljanje API.** Samostojni razredi opravil s prilagoditvijo `Dispatchable`, tipiziranimi lastnostmi konstruktorja kot vsebino in deklaracijami `$tries`/`$timeout`/`$backoff` v razredu. Razred `readonly` tem lastnostim ne more dodeliti privzetih vrednosti, zato jih deklarirajte v običajnem razredu z nespremenljivimi promoviranimi lastnostmi konstruktorja.
- **Cevovod vmesne programske opreme.** Vmesna programska oprema v slogu čebule za omejevanje hitrosti, dušenje izjem, enolična opravila in logiko po meri. Določi se za posamezno opravilo z metodo `middleware()`.
- **Pretočni koraki.** Vmesnik `StreamingStep` oddaja kose, ki se takoj shranijo v zbirko podatkov. Pri ponovnem poskusu se posredujejo prej shranjeni kosi, da se tok lahko nadaljuje tam, kjer se je ustavil. Idealno za odzive LLM in velike prenose.
- **Razširljiva plast predpomnilnika.** `CacheFactory` samodejno zazna APCu ali uporabi predpomnilnik v pomnilniku. Lastna zaledja implementirajo `Contracts\Cache`. Interno se uporablja za poizvedbe omejevalnika hitrosti in stanja čakalne vrste.
- **Paketna obdelava in veriženje.** Pošljite skupine opravil v izvajanje s povratnimi klici `then`/`catch`/`finally` in sledenjem napredku ali zaporedno verižite opravila, pri čemer je vsako odvisno od zaključka prejšnjega.
- **Trajni zamiki in čakanja.** `delay()` dodaja zamike, varne ob ponovnem zagonu procesa. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` in `wait_for_workflow()` omogočajo, da poteki dela čakajo na zunanje dogodke ali druge poteke dela, ne da bi proces PHP ostal aktiven.
- **Dinamična zanka za vsak element.** `for_each()` razširi delo vej, odkritih med izvajanjem, na podlagi stanja poteka dela ter podpira načine dokončanja »vsi uspešni«, »prvi uspešni« in »potrebna kvota«.
- **Asinhroni predaji potekov dela.** `start_workflows()` spremeni med izvajanjem odkrite elemente v neodvisne poteke dela najvišje ravni, na katere je mogoče pozneje počakati.
- **Sprožilci dejanj WordPress.** `on_action()` preslika jedrna dejanja ali kavlje dejanj vtičnikov v trajna pošiljanja potekov dela z nadzorom pogojev in idempotentnostjo.
- **Trajni artefakti.** Shranite imenovane izhode potekov dela zunaj glavne zbirke stanj in jih ohranite pri pregledu stanja, CLI, izvozu in ponovnem predvajanju.
- **Zaščitni mehanizmi potekov dela.** `version()`, deterministični zgoščeni odtis definicije, idempotentni ključi pošiljanja in proračuni potekov dela olajšajo pregled izvajanj v slogu agenta ter otežijo podvajanje ali nenadzorovano dolgotrajno izvajanje.
- **Upravljanje virov.** Skupine sočasnosti, stroškovne enote, proračuni potekov dela in sprejemanje delavcev pomagajo ohranjati drago delo v slogu agenta znotraj določenih omejitev.
- **Kompenzacija korakov.** `compensate_with()` in `compensate_on_failure()` zagotavljata kavlje za povrnitev dokončanih korakov, ko so poteki dela preklicani ali spodletijo.
- **Srčni utripi.** Dolgotrajni koraki pošiljajo srčne utripe in tako preprečujejo, da bi sistem za obnovitev zastalih opravil ponovno prevzel aktivno delo.
- **Sledenje potekom dela.** Vsak prehod koraka se zabeleži skupaj z vhodom, izhodom, stanjem pred in po njem, kontekstom, artefakti, kosi, napakami ter odpravljanjem napak s potovanjem skozi čas prek `workflow_state_at()`.
- **Vzporedni koraki.** Zaženite korake sočasno in pred nadaljevanjem počakajte, da se vsi dokončajo.
- **Pogojno razvejanje.** Preskočite na imenovane korake glede na predhodno stanje z uporabo `_next_step`.
- **Izvajanje potekov dela.** Zaženite podrejene poteke dela, ki vrnejo rezultate nadrejenemu.
- **Čakalne vrste s prednostjo.** Štiri ravni (nizka, običajna, visoka, nujna) prek tipsko varnih enumeracij PHP.
- **Delavci za več čakalnih vrst.** V enem delavcu obdelujte več čakalnih vrst s strogim upoštevanjem prednostnega vrstnega reda.
- **Omejevanje hitrosti.** Omejitve izvajanja za posamezen obravnavalnik z drsečim oknom.
- **Ponavljajoča se opravila.** Načrtovanje na podlagi intervalov in cron z nastavljivimi pravilniki za prekrivanje (dovoli, preskoči, shrani v medpomnilnik).
- **Preklic potekov dela.** Prekličite poteke dela v teku in sprožite registrirane obravnavalnike čiščenja.
- **Obrezovanje stanja.** Samodejno odstranite stare izhode korakov, da ohranite obsežno stanje potekov dela obvladljivo.
- **Sočasnost delavcev.** `--workers=N` razcepi več procesov in jih samodejno znova zažene ob sesutju.
- **Celovit nadzor.** Beleženje v zbirki podatkov, meritve za posamezne obravnavalnike in spletni kavlji dogodkov.
- **Pripomočki za testiranje.** `QueueFake` beleži poslana opravila in pakete za preverjanja v enotskih testih.
- **Atributi PHP.** `#[QueuetyHandler('name')]` za registracijo obravnavalnikov brez nastavitev.

## Kako deluje

Delavci se izvajajo v dolgotrajnem procesu WP-CLI in prevzemajo opravila neposredno iz MySQL. Vrstice čakalne vrste, stanje potekov dela, dnevniki, paketi, signali in pretočni kosi so shranjeni v MySQL, zato ponovni zagon delavcev ne povzroči izgube stanja orkestracije.

Poteki dela razdelijo dolgotrajno delo na korake. Izhod vsakega koraka se shrani v skupno zbirko stanj v zbirki podatkov. Če PHP preneha delovati sredi koraka, delavec ta korak poskusi znova, pri čemer ohrani vse predhodno stanje. Meja koraka je ena transakcija MySQL: posodobitev stanja, dokončanje opravila in uvrstitev naslednjega koraka v čakalno vrsto se izvedejo atomsko.

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

## Zahteve

- PHP 8.2 ali novejši
- WordPress 6.4 ali novejši
- MySQL 8.0+ ali MariaDB 10.6+, ker delavci prevzemajo opravila z uporabo `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` ali `pdo_mysql` v izvajalnem okolju PHP, ki nalaga WordPress in WP-CLI
- WP-CLI za zagon namenskih delavcev z `wp queuety work`
- Razširitvi `pcntl` in `posix` PHP za skupine delavcev (`--workers`, `--min-workers`, `--max-workers`)

Za namestitev glejte [Uvod](https://queuety.inline0.dev/sl/docs/getting-started).