# Ievads

Queuety ir WordPress spraudnis, kas nodrošina ātru uzdevumu rindu, noturīgu darbplūsmu dzinēju un noturīgu stāvokļu mašīnas izpildvidi. Darba procesi paņem uzdevumus tieši no MySQL un apstrādā tos ilgstošā WP-CLI procesā. Izpildvidei PHP, kas ielādē WordPress un WP-CLI, ir nepieciešams vai nu `mysqli`, vai `pdo_mysql`.

## Kāpēc Queuety?

WordPress nav īstas fona uzdevumu sistēmas. `wp_cron` darbojas tikai tad, kad kāds apmeklē lapu. Action Scheduler noklusējuma izpildmehānisms izmanto WP-Cron un HTTP pieprasījumus uz to pašu vietni; katrs apstrādā uzdevumu partijas ne ilgāk kā 30 sekundes. LLM API izsaukumu, kas ilgst 60 sekundes, pārtrauc PHP 30 sekunžu taimauts. Nav iespējams palaist vairāku soļu procesus, kas iztur avārijas un atsāk darbu no vietas, kur tas tika pārtraukts.

Queuety to nodrošina ar trim pamatkomponentiem:

1. **Uzdevumi** fona darbam bez gaidīšanas uz rezultātu
2. **Darbplūsmas** noturīgiem vairāku soļu procesiem ar saglabātu stāvokli
3. **Stāvokļu mašīnas** ilgstoša dzīves cikla stāvokļa modelēšanai, ko vada notikumi

## Īss piemērs

Nosūtiet uzdevumu, izmantojot moderno 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!' );
```

Vai izmantojiet klasisko pieeju, norādot apdarinātāja nosaukumu:

```php
use Queuety\Queuety;

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

Palaidiet noturīgu darbplūsmu:

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

Modelējiet ilgstošu sesiju ar stāvokļu mašīnu:

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

Palaidiet darba procesu:

```bash
wp queuety work
```

Ja veidojat aģenta tipa sistēmu, sāciet ar [Aģentu orkestrēšana](https://queuety.inline0.dev/lv/docs/workflows/agent-orchestration). Tajā parādīts, kā kopā darbojas plānotāja un izpildītāja plūsmas, cilvēka pārskatīšanas vārtejas un gaidīšana uz citām darbplūsmām.

Ja sistēma ir notikumu vadīta un darbojas ilgstoši, līdztekus darbplūsmām sāciet ar [Stāvokļu mašīnas](https://queuety.inline0.dev/lv/docs/state-machines).

Ja vēlaties skatīt pilna cikla integrācijas piemērus, skatiet [Piemēri](https://queuety.inline0.dev/lv/docs/examples), kur tagad iekļauti uz Neuron balstīti modeļi pakalpojumu sniedzēju maiņai, straumēšanai, atkārtotai pārskatīšanai ar atmiņas atbalstu un atkarīgām darbplūsmām.

Ja vēlaties sākt darbplūsmas no WordPress domēna notikumiem, piemēram, `save_post`, skatiet [Darbību aktivizētāji](https://queuety.inline0.dev/lv/docs/features/action-triggers).

Ja vēlaties izmantot DB atbalstītu izpildvidi ārpus WordPress, skatiet [Atsevišķa izmantošana](https://queuety.inline0.dev/lv/docs/features/standalone-use).

## Galvenās atšķirības

- **Ātra izpilde.** Darba procesi piekļūst MySQL rindai tieši un izvairās no cron katram pieprasījumam, kas palēnina fona darbu WordPress.
- **Noturīgas darbplūsmas.** Vairāku soļu procesi ar saglabātu stāvokli iztur PHP taimautus, avārijas un atkārtotus mēģinājumus. Katra soļa robeža ir atomāra MySQL transakcija.
- **Skaidri definētas stāvokļu mašīnas.** Modelējiet tērzēšanas sesijas, apstiprināšanas procesus un citus ilgstošus dzīves ciklus ar nosauktiem stāvokļiem, aizsargātām pārejām, rindā ievietotām darbībām, kas tiek izpildītas, ieejot stāvoklī, un noturīgām notikumu laika skalām.
- **Mūsdienīga nosūtīšanas API.** Patstāvīgas uzdevumu klases ar `Dispatchable` iezīmi, tipizētām konstruktora īpašībām kā datiem un klasē deklarētiem `$tries`/`$timeout`/`$backoff`. `readonly` klasei šīm īpašībām nevar norādīt noklusējuma vērtības, tāpēc deklarējiet tās parastā klasē ar nemaināmiem konstruktora parametriem, kas tiek paaugstināti par īpašībām.
- **Starpprogrammatūras konveijers.** Sīpola tipa starpprogrammatūra ātruma ierobežošanai, izņēmumu slāpēšanai, unikāliem uzdevumiem un pielāgotai loģikai. Tiek deklarēta katram uzdevumam ar `middleware()` metodi.
- **Straumēšanas soļi.** Saskarne `StreamingStep` nodod fragmentus, kas nekavējoties tiek saglabāti datubāzē. Atkārtotā mēģinājumā tiek nodoti iepriekš saglabātie fragmenti, lai straumi varētu turpināt no pārtraukuma vietas. Ideāli piemērots LLM atbildēm un lielām lejupielādēm.
- **Pievienojams kešatmiņas slānis.** `CacheFactory` automātiski nosaka APCu vai izmanto atmiņā esošu kešatmiņu. Pielāgotas aizmugursistēmas implementē `Contracts\Cache`. Iekšēji to izmanto ātruma ierobežotāju meklēšanai un rindas stāvoklim.
- **Partiju apstrāde un ķēdes.** Nosūtiet uzdevumu grupas ar `then`/`catch`/`finally` atzvanīšanas funkcijām un progresa izsekošanu vai secīgi sasaistiet uzdevumus, katram gaidot, līdz tiek pabeigts iepriekšējais.
- **Noturīgas aizkaves un gaidīšana.** `delay()` nodrošina aizkaves, kas saglabājas pēc procesa restartēšanas. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` un `wait_for_workflow()` ļauj darbplūsmām gaidīt ārējus notikumus vai citas darbplūsmas, neuzturot aktīvu PHP.
- **Dinamiska iterācija katram elementam.** `for_each()` paplašina izpildes laikā atrastos atzarojumu uzdevumus no darbplūsmas stāvokļa un atbalsta pabeigšanas režīmus: visi veiksmīgi, pirmais veiksmīgais un kvorums.
- **Asinhronas darbplūsmu nodošanas.** `start_workflows()` pārvērš izpildes laikā atrastos elementus neatkarīgās augstākā līmeņa darbplūsmās, kuras var gaidīt vēlāk.
- **WordPress darbību aktivizētāji.** `on_action()` pārveido pamata vai spraudņa darbību āķus par noturīgiem darbplūsmu nosūtījumiem ar vārteju pārbaudēm un idempotenci.
- **Noturīgi artefakti.** Saglabājiet nosauktus darbplūsmu rezultātus ārpus galvenās stāvokļa datu kopas un iekļaujiet tos statusa, CLI pārbaudes, eksportēšanas un atkārtošanas procesos.
- **Darbplūsmu aizsargmehānismi.** `version()`, deterministiska definīcijas jaucējvērtība, idempotenti nosūtīšanas taustiņi un darbplūsmu budžeti atvieglo aģenta tipa izpildes pārraudzību un palīdz novērst dublēšanos vai nekontrolētu darbību.
- **Resursu pārvaldība.** Vienlaicīguma grupas, izmaksu vienības, darbplūsmu budžeti un darba procesu piekļuves kontrole palīdz iekļaut dārgu aģenta tipa darbu noteiktās robežās.
- **Soļu kompensēšana.** `compensate_with()` un `compensate_on_failure()` nodrošina atsaukšanas āķus pabeigtiem soļiem, ja darbplūsmas tiek atceltas vai neizdodas.
- **Signāli.** Ilgstoši izpildāmi soļi sūta signālus, lai novecojušu uzdevumu atkopšanas sistēma neatgūtu aktīvo darbu.
- **Darbplūsmu izsekošana.** Katra soļa pāreja tiek reģistrēta kopā ar ievadi, izvadi, stāvokli pirms un pēc, kontekstu, artefaktiem, fragmentiem, kļūdām un ceļošanas laikā atkļūdošanas iespējām, izmantojot `workflow_state_at()`.
- **Paralēli soļi.** Izpildiet soļus vienlaikus un gaidiet, līdz tie visi ir pabeigti, pirms turpināt.
- **Nosacījumu sazarojumi.** Izmantojiet `_next_step`, lai, balstoties uz iepriekšējo stāvokli, pārietu uz nosauktiem soļiem.
- **Darbplūsmu palaišana.** Sāciet pakārtotās darbplūsmas, kuru rezultāti tiek nodoti atpakaļ vecākprocesam.
- **Prioritāšu rindas.** Četri līmeņi (Low, Normal, High, Urgent), izmantojot tipdrošus PHP enum.
- **Vairāku rindu darba procesi.** Apstrādājiet vairākas rindas, ievērojot stingru prioritāšu secību vienā darba procesā.
- **Ātruma ierobežošana.** Izpildes ierobežojumi katram apdarinātājam ar slīdošu logu.
- **Periodiski uzdevumi.** Uz intervāliem un cron balstīta plānošana ar konfigurējamām pārklāšanās politikām (atļaut, izlaist, ievietot buferī).
- **Darbplūsmu atcelšana.** Atceliet palaistās darbplūsmas un aktivizējiet reģistrētos tīrīšanas apdarinātājus.
- **Stāvokļa attīrīšana.** Automātiski noņemiet vecos soļu rezultātus, lai pārvaldītu lielus darbplūsmu stāvokļus.
- **Darba procesu vienlaicīgums.** `--workers=N` sadala vairākos procesos un automātiski restartē tos pēc avārijas.
- **Pilna pārraudzība.** Žurnalēšana datubāzē, metrika katram apdarinātājam un notikumu tīmekļa āķi.
- **Testēšanas rīki.** `QueueFake` reģistrē nosūtītos uzdevumus un partijas, lai tos varētu pārbaudīt vienību testos.
- **PHP atribūti.** `#[QueuetyHandler('name')]` apdarinātāju reģistrēšanai bez konfigurācijas.

## Kā tas darbojas

Darba procesi darbojas ilgstošā WP-CLI procesā un paņem uzdevumus tieši no MySQL. Rindas ieraksti, darbplūsmu stāvoklis, žurnāli, partijas, signāli un straumēšanas fragmenti atrodas MySQL, tāpēc, restartējot darba procesus, orķestrēšanas stāvoklis netiek zaudēts.

Darbplūsmas sadala ilgstošu darbu soļos. Katra soļa izvade tiek saglabāta koplietojamā stāvokļa datu kopā datubāzē. Ja PHP pārtrauc darbu soļa vidū, darba process atkārto šo soli, saglabājot visu iepriekšējo stāvokli. Soļa robeža ir viena MySQL transakcija: stāvokļa atjaunināšana, uzdevuma pabeigšana un nākamā soļa ievietošana rindā notiek atomāri.

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

## Prasības

- PHP 8.2 vai jaunāka versija
- WordPress 6.4 vai jaunāka versija
- MySQL 8.0+ vai MariaDB 10.6+, jo darba procesi paņem uzdevumus, izmantojot `SELECT ... FOR UPDATE SKIP LOCKED`
- `mysqli` vai `pdo_mysql` izpildvidē, kas ielādē WordPress un WP-CLI PHP
- WP-CLI īpašu darba procesu palaišanai ar `wp queuety work`
- Paplašinājumi `pcntl` un `posix` PHP darba procesu pūliem (`--workers`, `--min-workers`, `--max-workers`)

Skatiet [Darba sākšana](https://queuety.inline0.dev/lv/docs/getting-started), lai uzzinātu par instalēšanu.